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ERRATA 
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overstriking T, i and n , respectively, with ° and not O. The symbol for outer product is 
not "O.". 
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Disclaimer 



Waterloo Computing Systems Limited makes no representation or warranty with respect to 
the adequacy of this documentation or the programs which it describes for any particular 
purpose or with respect to its adequacy to produce any particular result. In no event shall 
Waterloo Computing Systems Limited, its employees, its contractors or the authors of this 
documentation be liable for special, direct, indirect or consequential damages, losses, costs, 
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PREFACE 



APL is a powerful and concise notation which can be used to communicate algorithms 
between people or between a person and a computer. The name APL is an acronym for "A 
Programming Language,' ' which was the title of a book published in 1962 by the inventor of 
APL, Kenneth E. Iverson. Since the late 1960's the notation itself has remained relatively 
unchanged, although features have been added to facilitate its use with the computer. 

Waterloo MicroAPL for the SuperPET follows closely the IBM internal standard for 
APL written by A. D. Falkoff and D. L. Orth and published in 1979 by the Association for 
Computing Machinery. All of the standard language primitives are included. System 
features are those consistent with a single user environment. Extensions include system 
functions supporting Hie access, the reading and modification of memory, and the execu- 
tion of machine language subroutines. 

This manual is presented in two parts. The first part is a tutorial intended to introduce the 
new user to the language and system features. The second part is a comprehensive reference 
manual. Much of the reference manual should be read or skimmed by the new user, 
although Chapter 6, which contains the detailed definitions of all the primitive functions 
and operators, should be deferred until needed. 
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Introduction 



This Tutorial is intended to provide an introduction to the basic concepts and facilities of the 
APL computer language as implemented on the Commodore Super PET. It is composed of a 
number of short topics with accompanying notes which illustrate each point. 

Getting Started 

Before turning the machine on, make sure the switches are set at 6809 and R/W. Then turn 
on the power switch on the SuperPET and disk (and printer if attached). The following 
menu should appear. 

Waterloo microSystems 

Select: 

setup 

monitor 

apl 

basic 

edit 

fortran 

pascal 

development 

Insert the system diskette in drive 1 and a data diskette in drive 0. Then select APL by typ- 
ing apl and pressing return. 

There will be a pause of about 1 minute while the APL language translator is loaded into 
the machine. Then a message similar to the following will appear: 

WATERLOO MICRO APL 

COPYRIGHT 1981 BYWA TERLOO COMPUTING SYSTEMS 

LIMITED 
CLEAR WS 



Now the APL system is ready for use. 
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Simple Arithmetic Functions 



The APL system manipulates numbers in the usual manner using the functions of addi- 
tion (+), subtraction (— ), multiplication (X), division (-;-) and exponentiation (*). Type 
each of the following simple expressions on the keyboard hitting the RETURN key after 
each one. 

(a) 5+6 (b) 3-1 

11 2 

(c) 18X3 (d) 3^4 

54 0.75 

(e) 2*3 (f) 3-4 

8 "~1 

(g) 2*. 5 

1.41421356 



NOTES: 

1 The symbols H — X -J- and * are called functions. Since each has 2 arguments 

(one on the left and the other on the right) they are called dyadic functions. 
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2 The result of example (0 is a negative number. The symbol for negative (~) should 
not be confused with the subtraction symbol (— ). 

3 Numbers in APL are displayed with 9 digits of accuracy as in example (g). 



Consider these examples: 

(h) (8-4)+ 1 
5 

(i) 8-(4+l) 
3 

0) 8-4+1 
3 



NOTES: 

1 These expressions are more complex, each containing a number of functions and 
arguments. 

2 Example (h) uses a pair of parentheses to force the subtraction (8 —4) function to 
be evaluated before the addition. 

3 Example (i) uses parentheses to force the addition to be evaluated first. 

4 As shown in (j), expressions are evaluated from right to left if no parentheses exist 
to indicate otherwise. 

5 The numbers used in these examples are referred to in APL as scalars. 
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Storing Numbers 



Numbers can be remembered by the APL system through the use of numeric variables 
which are defined by the programmer. 

(a) K/&4 -^79.45 

The assignment function (<-) is used to save the number 79.45 in the 
variable VISA. It may represent an amount owed to a credit company. 

The names given to variables can be composed of up to about 80 
characters. The first must be a letter of the alphabet, while the remainder 
can be any letter or number, or the underscore symbol ( ). 

(b) VISA 
79.45 



The contents of a variable can be displayed by typing its name. 
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(c) VISA-50 
29.45 

AfASTER-^m.15 
VISA+MASTER 

380.6 

Variables such as VISA and MASTER can be used in expressions. 

(d) KK/irMASTER 
301.15 

The greater of two niunbers can be computed with the dyadic function 
maximum (0. 

(e) WISAIMASTER 
79.45 



The lesser of the two numbers can be computed with the dyadic 
mimimum (L). 
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Lists of Numbers 



Many applications require manipulation of lists of numbers. APL has the ability to store 
such lists of numbers in a single variable. 

(a) CARDS<r-79.45 301.45 65 300.2 

The above list of 4 numbers is stored (using <- ) in the variable CARDS. 
Such lists are called vectors. This one could represent the various 
amounts owed to 4 credit companies. 

(b) CARDS 
79.45 301.45 300.2 

The contents of a vector are displayed by typing its name. 

(c) pCARDS 
4 

The number of elements in or length of a vector can be computed using 
the shape function (p). 

This is an example of a monadic function since it has only one argument. 



10 



Tutorials 



(d) CARDS-20 
59.45 281.45 45 280.2 

CARDS^l 
39.725 150.725 32.5 150.1 

The arithmetic functions (+ — X ^ * ) can be used to perform calcula- 
tions on all elements of a vector. 

(e) +/CARDS 
746.1 

The sum of the elements in a vector can be computed using the plus reduc- 
tion function (+/) 

+/CARDSX.18 

134.298 

Since expressions are evaluated right to left, tliis multiplies each element 
in CARDS by . 18 and then totals the elements of the resulting vector. 

i+/CARDS)-^pCARDS 

186.525 

This computes the average of the elements in the vector CARDS. 

(f) [/CARDS 
301.45 

The function U is used to compute the maximum element in a vector. 
L/CARDS 

65 

Similarly L/ computes the minimum element in a vector. 

(g) i8 

1 2 3 4 5 6 7 8 

The monadic index generator function (t) generates a vector of the in- 
tegers from 1 to the value of the specified argument. 
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(h) 



?10 



6 



?10 



3 



The monadic roll function (?) generates a random integer between 1 and 
the specified argument (in this case 10). 

3?10 

4 8 2 

3? 10 

2 7 6 

The dyadic deal function (?) generates a vector of random numbers 
without any duplicates. The left argument specifies how many numbers 
are to be generated and the right argument defines the range. 



It is often desirable to perform operations involving more than one list of numbers. In 
these applications functions are performed on pairs of vectors. 



CARDSXRATE 
14.301 63.3045 9.1 51.034 

The first line creates a vector called RA TE. It might represent the interest 
rates charged by 4 credit companies. The second line multiplies each ele- 
ment of RA TE by the corresponding element in CARDS and displays the 
result. Note that both RA TE and CARDSmmt have the same number of 
elements (i.e., they must have the same length). 



At this point we have created two vectors named CARDS and RA TE. We may wish to 
leave the system for a time and return later to continue. To preserve the data we have 
created, it is necessary to save the contents of our workspace. 



0) 



RATE->-.l8 .21 .14 .17 



G) 



)SAVETHISIVS 
SA VED 81/01/07 00:49:44 THISWS 



This is a system command that causes the contents of the workspace to be 
recorded on a diskette in drive 0. 
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(k) )LOAD THISWS 

&4KED 81/01/07 00:49:44 

This system command is used to restore the workspace to its state at the 
time when the )SA VE was done. 

0) )LIB 

This system command will display a list of all the workspaces which have 
been saved. 

(m) )DROP THISWS 

Workspaces can be removed from the library by use of the )DROP com- 
mand. 

(n) )VARS 

This system command will display a list of all the variables defined in this 
workspace. 
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Manipulating Character Data 



As well as performing arithmetic calculations, most computer applications must 
manipulate character data such as names, addresses, etc. APL treats such items of data as 
arrays of characters. 

(a) NAME<-'SMITH' 

The character data enclosed between the quote symbols is assigned to the 
character variable NAME, 

NAME is a vector of 5 characters. 

pNAME 



The shape function (p) computes the length of a character vector. 
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(b) FIRSTNAME^'JACK' 
FULLNAME^FIRSTNAME.NAME 
FULLNAME 

JACKSMITH 

FULLNAME^FIRSTNAME.' '.NAME 
FULLNAME 
JACK SMITH 

The dyadic catenation function (,) is used to create longer vectors from 
two shorter ones. 

(c) NAME*-' SMITH' 
IMAME 

S 

3WAME 

SMI 

~~3WAME 

ITH 

The dyadic function take (t) can be used to select a number of elements 
from the beginning or end of a vector. 

(6WIRSTNAME), NAME 
JACK SMITH 



The take function can be used to pad blank characters onto a character 
vector. 
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(d) NAME14\ 
T 

An index or subscript enclosed in square brackets and following the 
name of a vector indicates that the element in the specified position is to 
be selected from the vector. In this case the 4th character of 'SMITH' is 
selected. 

NAMEll 3 5] 

SIH 

If a list or vector of subscripts is specified, the corresponding elements 
are all selected to form a new vector. 

NAMEll+i3] 

MIT 

Using vector arithmetic and the index generator function , a substring can 
be extracted from a vector. 
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Data Comparisons 



A very important facility of any computer is the ability to determine the relationships be- 
tween various elements of data, both numeric and character. APL uses the functions equals 
(=), not equal (^), greater than (>), greater than or equal (>), less than (<), less than or 
equal (<), and (A), or (V) and not (~) to perform these comparisons. 

Comparison of items in APL is accomplished by the evaluation of a function which is found 
to be either True (represented by 1) or False (represented by 0). 

(a) VISA*-79A5 
VISA=0 



When the expression VISA=0 is evaluated it is found to be false since 
VISA is 79.45. Therefore the expression is given the value 0. 

VISA>0 

1 

(VISA>0)A(VISA<100) 

1 

These conditions are true and each receives the value 1 indicating truth. 
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(b) CARDS<-79.45 301.45 65 300.2 
CARDS>m 

10 1 

This condition requires that each element of CARDS be compared to 
100. The first and third elements are not greater than 100 and so fail the 
test. They generate or false. The second and fourth elements are greater 
than 100 and generate 1 or true. Thus a vector is created which indicates 
the result of each of the comparisons 

(c) +/(CARDS> 100) 
2 

This expression computes how many elements of CARDS are greater 
than 100 by creating a vector of I's and O's and summing. 

It is possible to use the vector of O's and 1 's produced in this way to select certain elements 
from a vector creating a new vector. 

(d) 10 1 0/CARDS 
79.45 65 

The dyadic function compression (/) is used to select specific elements 
from the vector CARDS. Compression selects elements from the right- 
hand vector which have a corresponding 1 in the left-hand vector. 

{CARDS> my CARDS 
301.45 300.2 

The selection vector on the left of a compression function is often 
generated by the evaluation of a condition. Here we select all elements of 
CARDS which are greater than 100. 

(CARDS> myipCARDS 

2 4 

Here we determine which elements of CARDS are greater than 100 (they 
are the second and fourth). 
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Tables of Data 



Frequently, it is desirable to group items of data together in the form of a table or matrix. 
The elements of a matrix are arranged in rows and columns. 

(a) TABLE"-! 3pl 2 3 4 5 6 

TABLE 

1 2 3 
4 5 6 

The first line uses the dyadic function shape (p) to create a matrix with 2 
rows and 3 columns. The elements of the matrix are filled in from the vec- 
tor on the right side. Note the order in which the elements are inserted in- 
to the matrix. If there are not sufficient elements in the right hand argu- 
ment to fill the matrix, then the elements are re-used as many times as 
necessary. 

pTABLE 

2 3 

The monadic function reshape (p) can be used to compute the number of 
rows and columns in a matrix. This is called the shape of the matrix. Since 
this is a 2-dimensional matrix, it is said to have a rank of 2. 



TABLES OF DATA 
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Consider a consumer who has 3 credit cards which he uses for 2 different categories of 
purchases (say business and personal). 

(b) CHARGES-^1 3pl4.3 7.9 100.1 17.26 24 40 

CHARGES 
14.3 7.9 100.1 
17.26 24 40 

The first line creates a matrix with 2 rows and 3 columns and assigns 6 
values from the 6-element vector on the right. 

The second line displays the elements of the matrix. 

(c) +/[\]CHARGES 
31.56 31.9 140.1 

The plus reduction function along dimension [1] (i.e. , down the columns) 
causes a total to be produced for each column. This creates a row of totals 
giving a total for each credit company. 

+/[1\CHARGES 
122.3 81.26 

Similarly, plus reduction along dimension [2] (i.e., along the rows) 
causes a column of totals to be produced, one for each row. 

-{■/■¥{2]CHARGES 

203.56 

This computes the sum of the rows and then sums the resulting vector to 
give the total of all the numbers in the table. 
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(d) PAYMENTS^! 3p20 10 20 10 20 30 

PAYMENTS 
20 10 20 
10 20 30 

CHARGES— PA YMENTS 
~5.7 ""2.1 80.1 
7.26 4 10 

This computes the balance owing in each account. 

All the usual arithmetic functions ( + — X -s- *) apply to 
matrices. 

+/ll]CHARGES—PA YMENTS 
1.56 1.9 90.1 

This computes how much we still owe each credit company. 

Character data can be arranged in matrices or tables as well. The elements of a character 
matrix are single charaaers. 

(e) COMPANY-^3 6p'VISA MASTERAMEX 
COMPANY 

VISA 

MASTER 

AMEX 

The first line creates a matrix of characters called COMPANY. Each of 
the 3 rows in the matrix is composed of 6 characters. 

In general, matrices or arrays can have as many dimensions as the appUcation demands. 
They can be viewed as tables of tables. 
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Indexing 



Previous tutorials have discussed vectors and matrices of numbers and characters. It is 
sometimes desirable to perform operations on selected elements of these tables. A technique 
called indexing or subscripting can be used for this purpose. 

(a) 10 3 41.1 62 

DATA 
14.2 10 3 41.1 62 

Here we have created a vector of 5 numbers. 

DATA12] 

10 

DATA[l 3 4] 
14.2 3 41.1 

These Unes display selected elements from the vector DATA. The 
numbers in the square brackets are called subscripts. A subscript can be a 
numeric scalar or vector. 



SimUar operations are possible with character vectors (see Tutorial 4). 
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(b) DATA[3]<-im 
DATA 

14.2 10 1000 41.1 62 

Any element of a vector can be replaced by using this combination of in- 
dexing and assignment. 

The various elements of a matrix can also be accessed individually with indexing. 

(c) CHARGES^! 3pl4.3 7.9 100.1 17.26 24 40 
CHARGES 

14.3 7.9 100.1 
17.26 24 40 

CHARGES12;3] 

40 

CHARGES[2;3]^0 

CHARGES 
14.3 7.9 100.1 
17.26 24 

Individual elements of a matrix (created as above) must be referenced by 
two indices or subscripts, specifying the row and column of the element 
respectively. 

In the case of matrices, complete rows or columns can be referenced. 

(d) CHARGESll;] 
14.3 7.9 100.1 

CHARGESl;3] 

100.1 

CHARGES[;2]*-0 

CHARGES 
14.3 100.1 
17.26 



Complete rows or columns of a matrix can be extracted or replaced using 
subscripts. 



INDEXING 
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(e) COMPANY->-3 6p'VISA MASTERAMEX 

COMPANY 

VISA 

MASTER 

AMEX 

COMPANY[Z-;\ 

AMEX 

COMPANY\\\\ 

VMA 

COMPANYl2;]*-'MCHG 
COMPANY 

VISA 

MCHG 

AMEX 



Row and column extraction and replacement can also be done on 
character arrays. 
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Combining Sets of Data 



In Tutorial 4, the catenation function was introduced as it pertained to character vectors. 
However, it has a more general application to vectors of all types. 

(a) DATA^IQ 13 47 
MORE->-6 5 7 

LOTS<-DA TA.MORE 
LOTS 
10 13 47 6 5 7 

The catenation function creates a single vector from two other vectors. 

(b) CHARGES*-! 3pl4.3 7.9 100.1 17.26 24 40 
CHARGES 

14.3 7.9 100.1 
17.26 24 40 
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NEW*-CHARGES,[l] 16 18 21 

NEW 
14.3 7.9 100.1 
17.26 24 40 
16 18 21 

These lines show how the catenation function is used to add a new row to 
the matrix ([1] means in the first dimension). 

NEW<-CHARGES,12] 16.1 14.7 
NEW 

14.3 7.9 100.1 16.1 
17.26 24 40 14.7 

A new column can be added in a similar manner ([2] means the second 
dimension). 

(c) CATEGORY-^2 Sp'BUSINESSPERSONAL' 

CATEGORY 
BUSINESS 
PERSONAL 

CA TEGOR Y. 05 CHARGES 
BUSINESS 14.3 7.9 100.1 
PERSONAL 17.26 24 40 

The thorn symbol (iP) specifies the monadic function format and is form- 
ed by overstriking the symbols T and o. It converts the numeric data in the 
matrix CHARGES to character data so catenation can be performed 
with the matrix CA TEGOR y (row by row). The result is a new character 
matrix. 

CATEGORY.! 2!^ CHARGES 
BUSINESS 14.30 7.90 100.10 
PERSONAL 17.26 24.00 40.00 



The dyadic function format converts numeric data to character and for- 
mats it. In this case, each number is converted to 7 characters with 2 digits 
after the decimal point. 
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Storing Instructions as Functions 



So far we have created various forms of numeric and character data in the workspace. 
Each time functions were to be performed on that data, the correct ^PI. statements had to 
be entered. It is often desirable to create a list of such statements or instructions in the 
workspace. These can then be invoked as a new function, thus avoiding re-entering all the 
lines again. 

(a) VSUM 
[11 

This line opens the definition of a function (or procedure or program) 
called SUM. We simply enter the statements we want to put in the func- 
tion in response to the line-number prompt by the system editor. 

VSUM 

[1] 'ENTER A LIST OF NUMBERS' 
[2] X'^n R GETNO'SFROMKB 

[3] 'SUM'=',^+/X P DISPLAY SUM OF NO'S 

[4] •AVG=^'M+/X)^pX fi DISPLAY AVG OF NO'S 
[5] V 



These Unes define the function SUM. 
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27 



Line [2] contains the symbol quad (□). Later, when this list of instruc- 
tions is being executed, it will allow vectors of numbers to be entered 
from the keyboard. 

Some lines contain the comment symbol ( O) (O overstruck with o). Text 
following this symbol provides documentation only. 

The del symbol (V) is also used to close the function in line [5]. 

(b) SUM 

ENTER A LIST OF NUMBERS 
□: 

I 7 18 4 "~2 
SUM = 28 
AVG = 5.6 

A function can be executed by simply typing its name. 

(c) V SI/MID] V 
[0] SUM 

[1 J 'ENTER A LIST OF NUMBERS' 

[2] X<-n fi GETNO'SFROMKB 

[3] 'SUM = ',^-¥/X P DISPLAY SUM OF NO'S 

[4] 'AVG = ',^{+/X)^ n DISPLAY AVG OF NO'S 
pX 

Example of listing a function. 

In order to modify the statements of a function definition, it is necessary to open the func- 
tion. Then changes can be made and the function closed. 
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(d) VSUMV2] 

This lists the function and leaves it open (i.e., the prompt for a new line 
[5] is displayed). Lines can now be added, inserted, modified or deleted. 
The cursor movement and the INST and DEL keys can be used to change 
existing lines. When all desired changes are made, the V symbol is used to 
close the function. 

The following are some examples of function editing: 

[4] 'AVERAGE='M+/X)^ Pi DISPLAY AVG OF NO'S 

pX 
[5] V 

Example of replacing a line in a function. 
[2.1] 'THERE ARE', ^pX): ELEMENTS' 
[2.2] V 

Example of inserting a line in a function. 
[A3] 
[4] V 

Example of deleting a line from a function. 

(e) yPNS 

This system command displays a list of all the functions which are defin- 
ed in the current workspace. 

(f) VFA 

[1] 'ENTER A WORD' 
[2] WORD^Ui 

[3] 'THE WORD HAS ',(^pWORD), ' CHARACTERS' 
[4] V 

This function illustrates how the input operation is used for character 
vectors. The symbol used for character input is quote quad (□) and is 
formed by overstriking the symbols ' and □. 
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(g) VFB WORD 
[1] N'>-+/'A'=WORD 

[2] 'THE LETTER A OCCURS ',(^N),' TIMES' 
[3] V 

In this example, the word to be examined is passed as a parameter to the 
function FB rather than being entered as input (as in (0). It would be used 
as follows: 

FB 'ACTUAL' 
THE LETTER A OCCURS 2 TIMES 

(h) )ERASEFB 

The system command )ERASE is used to erase a function or a variable 
from the workspace. 
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Controlling the Sequence of Execution 



Functions are frequently very complex combinations of APL statements. It is usually 
necessary to control the order of execution in these functions, repeating some statements a 
number of times (loop structures) and selectively executing others (if structures). This 
logical complexity is achieved in APL through the use of branching statements. 



(a) VCALC 

[1] 'ENTER SOME NUMBERS' 

[2] DATA<^a 

[3] TOTAL'>^-\-/DATA 

[4] IF:^(TOTAL < m)/ENDIF 

[5] 'TOTAL GREATER THAN 100' 

[6] ENDIF: 

[71 'TOTAL=',^TOTAL 

m V 



The function C4Z-Ccomputes and displays the total of a list of numbers. 
If that total is greater than 100, it also prints a message to that effect. 

Line [4] causes a branch to the line labelled ENDIF ([6]) when the condi- 
tion TOTAL < 100 is found to be true. The symbol indicates a possible 
branch. 
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The IF: in line [4] and the ENDIF: in line [6] are called labels and must 
be unique within the function. They are followed by the colon (:). Rules 
for forming label names are the same as those for forming variable names 
(see Tutorial 2). 



It is considered good practice to indent statements (such as line [5]) which 
are conditionally executed. 



(b) VCOMP 

[I] 'ENTER SOME NUMBERS' 
[2] DATA*-U 

[3] TOTALS ^- /DATA 

[4] IF.^(JOTAL < my ELSE 

[5] 'TOTAL GREA TER THAN 100' 

[6] -^ENDJF 

[7] ELSE: 

[8] 'TOTAL NOT GREATER THAN 100' 
[9] ENDIF: 

[10] 'TOTAL=',^TOTAL 

[II] V 



In this example, lines [5] and [6] are executed if TOTAL> 100 and lines 
[7] and [8] are executed if TOTVlLs 100. 



The -* ENDIF in line [6] causes an unconditional branch to line [9]. 

It is important to note that, while the APL language does not have the 
structured language constructs, good program structure can be achieved 
and revealed using controlled branching, well chosen labels and proper 
indenting. 
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VADDER 
[1] RPT: 

[2] 'ENTER SOME NUMBERS' 

[3] DATA*-D 

[4] TOTAL<-+/DATA 

[5] ->(TOTAL<0yEND 

[6] 'SUMOF, (^DATA), 'IS',^TOTAL) 

[7] -*RPT 

[8] END: 

[9] V 

The function v4Z?Z)£'/? repeatedly asks for a list of numbers for which it 
displays a total. This is done with a loop composed of lines [1] through 
[7]. 

Line [5] causes the loop to terminate when the calculated total is less than 
zero. 

V TRANSLATE 

[I] 'ENTER A NUMBER' 

12] i^n 

[3] CASE:-*(I=1 2 3)/CSl,CS2,CS3 
[4] 'NUMBER NOT IDENTIFIED' 
[5] -*END 
[6] CSl: 

[7] 'NUMBER IS ONE' 
[8] -*END 
[9] CSl: 

[10] 'NUMBER IS TWO' 

[II] -^END 
[12] CSS: 

[13] 'NUMBER IS THREET 
[14] £7VZ): 
[15] V 

Line [3] in this function performs a case test and selectively executes a 
group of statements based on the value of L If /= 1 control transfers to 
label CSl; if 1=2 control transfers to label CSl; etc. If the number 
entered is not 1 or 2 or 3, control passes to line [4]. 
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External Storage of Data as Files 



It is often desirable to transfer data between an APL workspace and external storage 
areas known as files. The simplest form of such a file can be viewed as a list of items of data. 
This is called a sequential file and is stored in the APL library and given a name. 

(a) 'TESrnCREATEe 

A file named TEST is created and given the tie-number 6. 

CHARGES*-! 3pl4.3 7.9 100.1 17.26 24 40 
CHARGES □ WRITE 6 

The shape, rank, type and all the data of the variable CHARGES are 
transferred to the file tied by number 6. 

COMPANY*-^ 6p'VISA MASTERAMEX 
COMPANY □ WRITE 6 



As before, all characteristics of COMPANY aie written to the file. 
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D UNTIE 6 
The file tied by number 6 is released. 

(b) 'TESTDTIE^ 

The file named TEST is tied to the workspace with the number 4. 

X<-nREAD4 
X 

14.3 7.9 100.1 
17.26 24 1 40 

The variable A" receives the shape, rank, type and all the data from the 
value stored in the file. 

X'>-UREADA 
X 

VISA 

MASTER 

AMEX 

Here the variable A!" receives all the characteristics of the next value stored 
in the file. 

UUNTIEA 
The file tied by number 4 is released. 

(c) 'TESrUTIEA 
•TESTHERASEA 

Files can be removed from the library with the function HERASE. The 
file being erased must be currently tied to the workspace. 
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(d) VCRTFILEA 

[1] ST*-AUCREATEZ 

12] -ENTER LINES {EOF TO STOP)' 

[3] RPT: 
[4] A'<-m 

[5] -*{A/'EOF=3'[X)/END 
[6] ST*-xnWRITE3 

[7] ^/?pr 

[8] £A©: 

[9] D UNTIE 3 

[10]V 



The above function creates a sequential file of character vectors entered 
from the keyboard. Line [1] creates the file using HCREA TE and gives it 
the name specified by parameter A. It also states that this file will be 
referred to as file number 3. 



Items from X are written to the file in line [6] using □ WRITE with ST 
receiving a string indicating the success or failure of the operation. 

When the entire file has been written, line [9J releases the file with 
nUNTIE and the file number becomes available for other uses. 



(e) VLISTFILEA 

[1] ST^AnTIE3 

[2] ^(0?tpS7)/0 

13] RPT: 

[4] X'^UREAD 3 

[5] -^{Sii=pUSTA TUS 3)/ END 

[6] U^X 

[7] -*RPT 

[8] END: 

[9] nUNTIE3 

[10]V 



This function retrieves the list of items from the file whose name is in A 
and displays them on the screen. Line [1] attaches the specified file using 
UTIE and states that it will be referred to as file number 3. 



Line [2] causes a transfer to line [0] (i.e. , exit from the function) if an er- 
ror occurs while attaching the file. 
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Line [4] uses Mfi^Z) to retrieve one item from the file and assign it to X 
After this operation, the function DSTA TUS (in line [5]) is used to check 
the result of the OREAD. When all the items have been retrieved, 
DUNTIE is used in line [9] to release the file. 
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Keyboard and Screen 



Keyboard 



Although the APL keyboard is similar in many ways to the standard keyboard, there are 
some major differences. 
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The capital letters A-Z are in their usual positions, but you do not press SHIFT to get 
them. There are no lower case letters in the APL character set. 

Many of the remaining characters are peculiar to APL and will be explained later. 

"Overstruck" Characters 

Besides the symbols shown on the keyboard diagram there are 18 other symbols that can be 
created by typing two symbols on top of each other (e.g. , by using the "cursor back" key). 
The 18 overstruck symbols and the two symbols which produce each of them are shown in 
the figure below. 
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Unused Symbols 

Some of the symbols in they4PZ, character set have no use in MicroAPL except as convenient 
graphic symbols. These are 
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Control Keys 

screen or cursor functions: 
Moves cursor left ("cursor back") 
Moves cursor right 
Moves cursor up 
Moves cursor down 
Moves cursor to next tab position 
Clears the screen and "homes" the cursor 
Moves cursor to top left hand corner 
"destructive backspace" 
Erase to end of line 
Opens space under the cursor 
Deletes characters and closes text. 
(Behavior is slightly different depending on whether there 
are nonblanks to the right of the cursor or not.) 

Full Screen Editing and the RETURN Key 

Whenever the APL system expects you to enter something from the keyboard, you may use 
the control keys to manipulate the screen in any way you wish, but nothing will be sent to 
APL until you press the RETURN key. This is the only rule you need to remember: when 
you press RETURN, the entire contents of the line the cursor was on (when you pressed 
RETURN) gets sent to APL. It doesn't matter what may be elsewhere on the screen. The rule 
applies equally whether you are in immediate mode or function definition mode. 



Several of the keys control 
<= CRSR 
= > CRSR 
CRSR 
CRSR 

TAB 

CLR 

HOME 

RUBOUT 

EEOL 

INST 

DEL 
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The Workspace and System Commands 



The active workspace is the environment within which you deal with APL. The principal 
contents of a workspace are variables and defined functions. When you begin an APL ses- 
sion the active workspace is empty; the message CLEAR WS confirms this. 

There are a number of system commands which permit you to manipulate workspaces. 
System commands are distinguished by the fact that they all start with a right parenthesis. 

)LIB 

)LIB libid 

The response is a listing of the directory for the diskette in drive of the disk unit, or else for 
the device designated by libid (see the System Overview Manual). For example, if you have a 
disk unit whose address is 9, not the usual 8, then )LIB DISK9/1 will give you the directory 
for the diskette in drive 1 of that unit. A lengthy listing can be interrupted by means of the 
STOP key. 

)CLEAR 

The active workspace is replaced by one without any defined functions or variables and with 
the workspace parameters ( DIO. OCT, DPP, DPW, DRL, OLX) set to their default 
values. The name of the workspace is set to null and is reported as CLEAR WS. The 
previously active workspace is gone. 
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)WSID 

The response is the name of the active workspace. 
)WSID wsid 

The name of the active workspace is changed to wsid. The response is its previous name. The 
parameter wsid is often just a name, like CHESS, but it can designate a device as well (e.g., 
DISK/l. CHESS). See the System Overview Manual. 

)SAVE 

The active workspace is saved under its current name (unless the name is null). 
)SAVE v/sid 

The active workspace is saved under the name wsid unless wsid doesn't match the current 
name and there already exists a workspace with the name wsid. (This is to prevent you from 
inadvertently overwriting one workspace with another.) After the SAVE, the active 
workspace will have the name wsid, whether it did before or not. 

The response to a SAVE is a timestamp derived from the current setting of the system clock 
(see OTS) together with the name under which the workspace was saved. The timestamp is 
saved with the workspace and is reported on subsequent loading. 

)LOAD wsid 

The named workspace replaces the active workspace. The active workspace is gone. The 
response is the timestamp saved with the workspace. 

)COPy wsid 
)COPY wsid names 

The named objects (functions and variables) are copied from the named workspace into the 
active workspace, replacing any objects therein having the same names. The parameter 
names is a string of names separated by blanks. If it is omitted, all the variables and func- 
tions (except objects beginning with □) are copied. 

)DROP wsid 

The designated workspace is deleted from the library. 
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)FNS 

The response is a list of the names of the deflned functions in the active workspace. 
WARS 

The response is a list of the names of the variables currently defined in the active workspace. 
Gncludes local variables if there are suspended functions.) 

)£R/1SE names 

Names is a string containing the names of variables and functions separated by blanks. The 
named objects are deleted from the active workspace. Response: normally none, but objects 
which could not be erased are reported. 

)SI 

The response is the current state indicator (see Deflned function execution). 
)SINL 

The response is as for )SI but with the local variables shown against each active function. 
)OFF 

APL is discontinued and control is returned to the miCTolanguage menu. 
)SYMBOLS 

The response is the current maximum nmnber of symbol table entries. 
)SYMBOLS number 



This has the same effect as )CLEAR except that the maximum number of symbol table en- 
tries is set to number. 
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)WSLIMIT 

The response is the first memory address beyond the current end of the workspace. 
)WSLIMIT numbeT 

The end of the workspace is changed to (number-1). 



NOTE: 

1 Program function key 3 (i.e. , shifted "3" on the numeric keypad) is equivalent to 

typing the three system commands )FNS, ) VARS and )SI. 
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Expressions 



An expression is a string of APL variables, functions, operators, numeric and character 
constants, parentheses and bracketed index expressions. 

As a general rule, an APL expression is evaluated from right to left, in the absence of 
parentheses. Although at first this sounds peculiar it is in fact what we are used to when we 
use the English language. For example, the sentence "The equivalent resistance is the 
reciprocal of the sum of the reciprocals of the given resistances." makes sense (to an elec- 
trical engineer!) when read from left to right, but as a prescription for computation it must 
be used from right to left, starting with "the given resistances" and ending with the 
specification of "the equivalent resistance." 

The equivalent /IPZ, expression is M< — -■\-/-^R . It, too, can be read from left to 
right, but is executed from right to left. 

Parentheses modify the order of execution in the usual way. 

There are no priority rules such as the common convention that ' 'multiplication and divi- 
sion are done before addition and subtraction." For example 3X4-H5 is 27, not 17. This 
makes life much simpler in an environment such as APL, in which there are dozens of func- 
tions like X,-r,+ and — . 

Subexpressions containing operators, like + .X are exceptions to the above. 
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Arrays 



Data in APL is not in general single quantities, but rectangular arrays of quantities. A table, 
or matrix, like 

2 3 ~4 
5 6.7 

is a rectangular 2 by 3 array of numbers. We say that its type is numeric, its rank is 2 and its 
shape is 2 3. 

In general, an APL array has, besides its elements, a type (numeric or character), a rank 
(the number of axes, or "coordinates," or "dimensions"), and a shape (a vector giving the 
length of each axis). 

A simpler array than a matrix is a list, or vector, like 

~7 2 3 5 

whose rank is 1 and whose shape is 4. 

There is an even simpler array than a vector. This is a single quantity, or scalar, like 3. 14 
whose rank is and whose shape is empty. 
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Empty arrays 

It is possible in APL to create an empty array, that is one having no elements at all. The rank 
and shape of an empty array are not restricted except that the shape vector contains at least 
one element which is zero. 

In general, the number of elements in an array is the product of the elements in its shape 
vector. 

Internal Representation: Numeric Data 

The elements of a numeric array are stored internally in a 5 byte floating point format. Thus 
the 2 by 3 matrix used in the above example requires 6X5 = 30 bytes of memory, plus the 
memory necessary for the shape vector, the rank and the type, plus some further overhead. 

MicroAPL does not take advantage of the compression which is possible when numeric 
arrays are known to be boolean or integer. 

Internal Representation: Character Data 

The elements of character arrays are stored one per byte, plus the same overhead as for 
numeric arrays. Thus the 3 by 5 matrix 

ABCDE 

FGHIJ 

KLMNO 
requires 15 bytes plus overhead. 

All 256 possible bytes are legal as the elements of character arrays. 
Numeric data: Input 

Numeric data elements are entered through the keyboard using the digits 0-9 and the sym- 
bols ~ ". and "£ ". 

The digits 0-9 and the decimal point are used in the normal way. 

The negative sign (which is located above the "2" on the keyboard, not above the 
" + ") and the " £ " (which means ' 'times ten to the power . . . ") are symbols similar to the 
decimal point in that they are regarded as being part of the representation of the number and 
not functions or operators. 
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Examples: 

2.35E2 is equivalent to ^235 
3.14£~3 is equivalent to 0.00314 

There must not be spaces within the representation of a number, and if E occurs, the 
number following it must be an integer. 

A numeric vector may be entered by typing a sequence of numeric elements separated by 
spaces, all on a single line. Larger vectors, and arrays of higher rank, must be formed from 
smaller ones by applying APL functions to them. 

Character Data: Input 

Character data elements which correspond to APL symbols can be entered through the 
keyboard. 

A character vector may be entered as a string of APL symbols without unintended spaces 
(space is an APL symbol), all on a single line. 

When a character vector is included as a character constant in an expression it must be 
enclosed in quotes, and any quote symbol which the vector itself contains must be made into 
two consecutive quote symbols. Thus the contraction of CANNOT would be input by 
means of the string 'CAN' 'T'. The length of the resulting vector is 5 and it contains one 
quote symbol. 

Fewer than half of all the possible byte values are interpreted internally as /IPZ, symbols. 
An application requiring the manipulation of bytes in general wiU usually create the 
character arrays by indexing HA V , not by getting them through the keyboard. 

Again, larger vectors, and arrays of higher rank, must be formed from smaller ones by ap- 
plying ylPL functions to them. 



Variables 

Every variable has a name which is a string of letters, digits and the underscore character 

( ). The flrst character of a name must be a letter. Names should be limited to 80 

characters. 
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A variable generally acquires a value (which is an array) by having one assigned or 
specified. Thus 

TAXURATE*-- 
27.4 

assigns the scalar value 27.4 to the variable called TAX_JIA TE. 

There may be several assignments within a single APL expression. For example 
A*- 1 +B*-0 is sometimes used to initialize to 1 and B to 0. This tends to reduce readability 
and should usually be avoided. 
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Defined Functions 



The defined function in APL is similar to a "program" in other languages, and in fact we 
will often use the term "program" interchangeably with "defined function." 

A workspace may contain a large number of defined functions and they need not bear any 
particular relation to each other. 

A defined function has a multiline representation. The first line, or header, establishes the 
name and syntax of the function, the names used for the parameters and the local names. 
The subsequent lines, or body, are the statements to be executed when the function itself is 
executed. 

The Header of a Defined Function. 
-Function name 

The names of defined functions are subject to the same rules as the names of variables. 
—Syntax 

The syntax of a function describes how the function name may appear in an expression. 
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A function may have 0, 1 or 2 explicit arguments. The arguments of a function are always 
data arrays. A function having no arguments is called niladic. A function having one argu- 
ment is called monadic and the argument appears to the right of the function name. A func- 
tion having two arguments is called dyadic and the arguments appear on either side of the 
function name. 

In addition to being niladic, monadic or dyadic, a function either produces an explicit 
result or it doesn't. This gives six syntactical forms to choose from for any given function. 



-Parameters 

The variables represented by L, R and Z in the above figure are called parameters. These are 
temporary names which exist for the purpose of function definition and execution only. 
They indicate the syntax of the function and they serve as names by which you can refer to 
the left argument, the right argument and the result in the body of the function definition. 
The function name and parameter names must all be distinct, but they may match other 
names in the workspace; that is, they have local significance only. If a result parameter is in- 
cluded in the syntax of a function then during execution a value must be specified for that 
variable or a VALUE ERROR will result when execution ends. 

-Local names 

It is often desirable to have other local names in defining a function. Names can be made 
local by Usting them in the header after the syntax, each name preceded by a semicolon. 

Thus the header /I R iX;B establishes a monadic function P with result A , right argu- 
ment R and local names A* and B. (Usually and B will be the names of variables, but they 
may also be the names of functions to be established by UFX. ) 

The name of the function being defined cannot be localized. The names of the parameters 
and the labels in a function are impUcitly local and should not appear in the local variable 



Niladic 

Monadic 

Dyadic 



No 
ExpUcit 
Result 

F 

F R 
L F R 



Explicit 
Result 
Z<-F 
Z*-F R 
Z*-L F R 



list. 



The Body of a Defined Function 



DEHNED FUNCTIONS 



53 



-Statements 

AnAPL statement is made up of any combination of the following components, in the order 
given. 

(1) A label; i.e., a name followed by a colon. 

(2) A branch arrow (->). 

(3) An expression. 

(4) Acomment; i.e., alamp symbol (R) (formed by overstriking D andO) 
followed by any string of characters. 



name: , -* expression 

V ' 


characters 




' y ' 


label 


comment 


Figure 5.1 


Statement 



Execution of a statement consists of evaluating its expression, if it has one, and taking action 
appropriate to the branch arrow, it there is one. 



XI: 

END: -*0 
— ► 

M*-^+/^R O EQUIV RESISTANCE 

REPEAT: -*{N>I<^I+\)/ REPEAT P ADELAY 
PtHOLDFOR ARRIVAL 

Figure 5 .2 Examples of Statements 



-Branches and Labels 

The statements in the body of a function are numbered 1, 2, .... If a statement includes a 
label, the value of the label is the number of the statement. The label is a local name. Care 
should be taken not to assign the same label name to more than one statement in a given 
function. 

The statements of a function are normally executed in the sequence in which they occur. 
This normal sequence can be modified bv the branch statement, that is, one containing a 
branch arrow. 
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The next statement to be executed after a branch statement is determined as follows: 

(a) If the branch statement has no expression then execution ceases, the cur- 
rent execution sequence is cleared off the execution stack and^PL awaits yoiu: 
next request. 

This statement is normally used manually to clear out the execution stack and 
get rid of local variables, but it can also be written into functions and used to 
abandon automatically the execution of a program when a fatal error is 
discovered. 

(b) If the branch statement has no expression then the value of the expression 
must be either (1) an integer scalar, or (2) a vector whose first element is an in- 
teger, or (3) an empty vector. 

In the first two cases the integer referred to is the number of the next statement 
to be executed. If the integer is not a vaUd statement number then execution of 
the function terminates and control returns to whatever caused execution to 
start. In particular, is not a vaUd statement number and is often used to cause 
termination of the function. 

In the third case, the empty vector, no branch occurs: the next statement to be 
executed is the one following the branch statement in normal sequence. 

A very common form for a "conditional branch" is exemplified by 

-*(I<N)/INVERT 

which can be read as 'if /<Nthen go to INVERT. INVERTis assumed to be 
the label on some statement in the function. 

A "case" construction can be obtained by 

-»(/=! 2 3)/CASEl,CASE2,CASE3 

or by 

-((XN;='~1 l)/NEGATIVE,ZERO,POSITIVE 
where as before the names to the right of the compression (/) symbol are 
assumed to be labels. 

The branch statement is extremely powerful and must be used with restraint, or you will 
create programs which are very difficult to understand. 
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Defming a Function 

A function can be defined or established in a workspace in one of three ways. 

(1) It can be copied from a stored workspace using the )COPy system com- 
mand. 

(2) It can be established by means of the system function CIFX. 

(3) It can be established by the use of the "del" function editor. 

The first two features are described elsewhere. 

To use the "del" editor to define a function, enter function definition mode by typing the 
character del (V) followed by the header of the function. The editor will prompt with a line 
niunber in brackets. Enter the statements of the body of the function one by one. 

To leave function definition mode, end a line, other than one containing a comment, with 
a del (V), or enter del in response to the line number prompt. 

Editing a Function 

To use the editor to revise the definition of an existing function, enter V followed by the 
name of the function. You caimot redefine the header this way: the name only is acceptable. 

The name of the function may optionally be followed immediately by an editing com- 
mand. Once you are back in fimction definition mode, every line you enter must be an 
editing command. 

Following is a list of the possible editing commands. 



Editing command Meaning 
[□] Display the existing definition. 

[□n] Display the function, starting at line n. 

[nD] Display line n only and leave the cursor on the line. 

[n] text Replace the contents of line n by text. (Note that no change will 

occur if text is blank. This is a safety measure.) The number n need 
not be an integer: if n falls between two existing lines, then the new 
line is inserted between those lines. 

[An] Delete line(s) n (n may be a vector). 
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It can be seen that the bracketed line number prompt that the system displays is merely an 
editing command. It is not necessary to delete it or move to a new line to enter a different 
command: the system ignores all but the last recognizable editing command on a line. 

During the editing process for a function the lines of the body are not renumbered 1 ,2,... 
immediately after deletion or insertion. Renumbering occurs after you leave function 
definition mode. 

For editing purposes only, the header is considered to be line 0, and it is displayed that way 
when [□] is executed. The entire header may be changed if desired, including the function 
name. 

Editing Hints 

Keep functions short. Functions longer than the screen (about 20 lines) are inconvenient to 
deal with. 

When editing an existing function, display it immediately and then use the screen editing 
controls to adjust the definition of existing lines. Don't forget to strike RETURN when you 
are satisfied with a line; otherwise your changes will not be recorded. 

Conversely if you have accidentally made garbage of a line of the function, don't hit 
RETURN, but use the cursor to get to a new line and ask for a redisplay. The garbage will 
not be recorded. 

Program function key 1 (i.e., shifted " 1 " on the numeric keypad) during function editing 
will close the function definition, then immediately reopen and display it . The effect is to get 
a clean, renumbered listing of the function. 

Errors During Function Editing 

The editor detects a variety of errors, all of which are repotted as DEFN ERROR. Here are 
some of the possible causes. 

— On Opening a Function Definition 

— ^The name of the intended function is aheady in use as a variable. 

— ^Attempt to respecify the header of an existing function. 

— Header is syntactically invalid. 



— Invalid function name (e.g., "3D"). 
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— ^You were already in function definition mode. 
— Function is pendent. (Clear the state indicator.) 
— Function name in locals list. 

— Function name and parameter names are not all distinct. 
— During Editing. 
— Invalid editing command. 

— ^Attempt to edit the header of a suspended or waiting function. 

If you get a SYNTAX ERROR during editing you were probably not in the editor at all. 
You may have executed V/^n]V instead of Vi^D], for example. 

Effect of Localization 

All names appearing in the header (except the function name itself), together with the names 
of all labels, are local names. Local names have only the significance assigned to them in 
their own function regardless of their significance in the calling environment, that is, before 
execution of the function began. The effect of this is that during the execution of the func- 
tion (and even if the function becomes suspended) there is no way to "see" the original value 
associated with a localized name. The original value is restored when execution of the func- 
tion terminates. 

Any name which is not local has the same significance that it had in the calling environ- 
ment. One of the effects of this is that a function cannot "hide" the value of its variables 
from any function which it calls. 

Executing Defined Functions 

In immediate execution mode, if you type a statement and press RETURN the statement is 
executed immediately. If, during the execution of the statement, the name of a defined func- 
tion is encountered, then that function is executed. This in turn involves executing 
statements (those of the function) and any functions that they refer to, and so on. This pro- 
cess normally ceases only when the statement you originally typed is completely executed. If 
the statement has an explicit result and the last thing executed was not an assignment {*-) the 
system displays the result on the screen. It then awaits your next command. 
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Suspension of Execution 

The execution of a defined function will stop prematurely if an error is encountered, if the 
STOP key is pressed, or through stop control (see below). The system returns to immediate 
execution mode. 

The function whose execution was interrupted is said to be suspended and all those func- 
tions which led to its execution and are not yet completed are referred to as pendent. A 
dyadic function whose left argument is being evaluated is said to be waiting. 

The suspended function can be restarted by entering a branch statement. In the case of 
stop control, no part of the Une has been executed and the function can be safely restarted 
with a branch to the line number in question. In the other two cases the point of interruption 
is indicated approximately by a caret (A). Whether the function can be restarted (even after 
the error, if any, has been fixed up) normally requures some analysis. 

A convenient way to restart a suspended function is to enter QLCsince DLCis a vector 
whose first element is the Une number at which execution is to be resumed. 

In the suspended state, most normal activities are possible, including the evaluation of ex- 
pressions and the execution of functions, but there are some limitations. 

1 . All names have their local significance (that is, the significance they 
had in the suspended function). 

2. Space may be limited by the inclusion in the workspace of the local 
variables of the suspended and pendent functions. 

3. Pendent functions cannot be edited. 

4. The header of a function which is suspended or waiting cannot be 
edited. 

5. Functions which are suspended, pendent or waiting cannot be erased. 

6. The workspace can be saved in this condition but it may not be subse- 
quently loadable by any different release of the MicroAPL system. 

NOTE: There may be ways, not prohibited by these limitations, to create an inconsistent 
workspace by manipulating halted functions. 
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In general it is best to "punt" (see below) after suspension of function execution unless 
you have a good reason not to. One good reason not to is if you are not sure what caused the 
error and wish to investigate further by listing variables or executing subexpressions of the 
one in error. It is sometimes useful in this case to save a copy of the workspace in its suspend- 
ed state (under a "temporary" name!) before doing anything that might make the trail hard 
to follow. 

Stop Control 

By the use of the system function DSTOP (see "System Functions") a function can be 
caused to stop in a suspended state just before executing a given line or lines. The function 
may be normally restarted safely by branching to the line number of the stop. 

Trace Control 

A trace of a function line is a display generated on the screen immediately after the execution 
of the line. The system function DTRACE is used to determine which lines are to be traced 
(see "System Functions"). Execution of the function is not halted. The display generated by 
a trace consists of a TRACE SET message, the Une number and the value, if any, of the ex- 
pression in the statement. 

State Indicator 

The system command )SI causes the state indicator to be displayed. The state indicator 
shows all the suspended (marked with an asterisk) and pendent functions. (It does not show 
the waiting functions.) The order of the display is the same as for dLC, that is, most recent 
first. 

For example: 

)SI 

H[3] * 

cm 

F12] * 
DLC 

3 7 2 

It is good practice to display the state indicator periodically to see that it is clear, and it is 
especially inportant when something mysterious seems to have happened: a function has 
disappeared, for instance, or an unusual WS FULL occurs. 
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"Punt" 

The statement -> is sometimes called a "punt" (the football term). It may be used as a Une of 
a defined function, as the response to a □ input request, or in immediate execution mode. Its 
effect in each case is the same: the currently executing function, or the latest suspended func- 
tion, is terminated, together with all the pendent functions which led to its execution. 



The state indicator may always be cleared by executing punt sufficiently many times. 
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Primitive Functions and Operations 



The term "primitive" refers to things that are available as part of the system without the 
necessity of defining them. 

The primitive functions and operations all have APL symbols reserved for them. Almost 
half of the symbols used for primitive functions actually represent two functions, one 
monadic and the other dyadic. Which is intended in a given expression must be determined 
from the context: the dyadic function is denoted if possible, i.e., if there is a left argument. 

NOTE: The symbol •• — ► used in the following is not APL notation. It means "is 
equivalent to." 

-Scalar Functions 

Scalar functions are functions defined on scalar arguments, yielding a scalar as a result, and 
which are extended to array arguments element by element. 

-Monadic Scalar Functions 

The monadic scalar functions are shown in Table A.l. 
Each of these functions has the same syntax as the familiar "negative" function. 
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Each takes only numeric arguments. Each can be applied element by element to an array 
argument, yielding an array of the same shape. 



—Arithmetic Functions 



R*- +B (Conjugate or indentity) The result is the same as the argument. +B < — ► 0+B 



R* — B (Negative) -B < — » 0-B 



R*-XB (Signum) X5is l.Oor 1 according to whether 5 is negative, zero or positive. 
Xfi< — * (B>0)-(B<0) 



R* — -B (Reciprocal) -^B < — ► 1 -^B. B must not be zero. 



/? <- L5 (Floor) IB is the greatest integer not greater than B. This result is modified in 
accordance with the system's comparison tolerance parameter. For example, 
if the comparison tolerance has its default value of about \£ ^8 then 
17.99999999 •• — ► 8. Formally, floor has the following definition. 



VR'>-FL X : N 



[l]N*-{XX)XLQ.5+\X 

[2] R*-N-(N-X) > nCTX 1 l\N 



V 



R*-W (Ceiling) IB is the least integer not less than B. Again the result is modified in 
accordance with comparison tolerance. rB< — ► —i—B 

R*-*B (Exponential) * 5 is e raised to the B' th power, where e is the base of natural 
logarithms (approximately 2.71828). 

R*- ®5 (Natural Logarithm) The inverse of the exponential function. ® * B < — * B 
* — ► * 9B. B must be greater than zero. 

|B (Magnitude) The absolute value of B. |B < — ► Br(-B). 

R<-IB (Factorial) iB< — ►BX(B-1)X(B-2)X...X2X1 andO* < — ► l.Bmustbea 
non-negative integer. 



R->-OB 



(Pi times) Pi times B where Pi is approximately 3.14159. 
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— Random Function 



R*-1B (Roll) IB is a random choice from the integers iB. Since iB is dependent on the 
current index origin, so is IB. B must be a positive integer. 



— Logical Function 



R*-~ B (Not)5mustbeOorl. -01 < — ►lO 



—Dyadic Scalar Functions 



The dyadic scalar functions are shown in Table A.2. 



Each of these functions has the syntax R*- A f B like the familiar "plus" function. Each 
takes only numeric arguments, except = and ^ which permit both numeric and character 
arguments. Each is extended to nonscalar arguments according to the following rules. 

a) If A and B are the same shape, the function f is applied to corresponding 
elements of A and B to give a result of the same shape; 

b) else, if A and B each have only one element, then the result has one element 
and is of shape equal to the shape of the argument having the greater rank; 

c) else, if one argument has only one element then it is extended to be the same 
shape as the other argument; 

d) else the arguments are not conformable and an error is reported. 



— ^Arithmetic Functions 



R^A +B (Plus) Addition. 
R<-A—B (Minus) Subtraction. 
R *-A XB (Times) Multiplication. 



R*-A -i-B (Divide) Division. B must not be zero unless ^4 is as well, and then 0^0 < — ► 1 . 



R<-ALB (Minimum) A LB is the lesser of and B. 
R*-A [B (Maximim) A TB is the greater of A and B. 
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R*-A * B (Power) A raised to the power B.A*Bis not defined if .4=0 and B<0 or if 
.4 < and B is not an integer. * 0< — > 1 

R*-A ®B (Logarithms) A 9B is the base A logarithm of B i.e., the power to which A 
must be raised to give B. A 9B< — >(®5)-^(®^). A and B must be positive, 
andif>l=l thenB=l. 

R*-A\B (Residue) is the remainder when 5 is divided by 0\B < — ► B. UA^O 
then R< — * B—A X LB-i-A . R will always lie between (inclusive) and A (ex- 
clusive) regardless of whether .4 is positive or negative. 

R *-A I B (Binomial coefficient) This is often read 'A out of B'. One interpretation of it 
is the number of combinations of B things taken>l at a time. A must be a non- 
negative integer. B may be any number. 



— Logical Functions 

R*-A/\B (And) 

R<-/lvfl (Or) 

R*-A AB (Nand) 

i?«-AY5 (Nor) 



In each case A and B must be or 1 . (See Table A.2) 



— Relational Functions 

R*-A<B (Less) 

R *-A < B (Less or equal) 

R<^A=B (Equal) 

R*-A>B (Greater or equal) 

R*-A>B (Greater) 

R*-Ai=B (Not equal) 



In each case is 1 if the relation holds, if it does not. A and/or B can be of 
type character only in the case of = and i^. 

The relational functions on numeric arguments are all subject to comparison 
tolerance. A is considered ("tolerantly") equal to B if and only if (\A—B) < 
(Comparison tolerance) X{\A)S{\B). 

The other five relational functions then use this version of equality in their 
definitions. 



AlB^-^\ 



if^=0 
if A>0 



BX{B-l)X...XiB+\-A))^ilA) 
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The comparison tolerance may be changed from its default value of about 
IE ^8 by means of the system variable OCT. 

The effect of comparison tolerance is to make 9=(3 * 2) < — ► 1 for example 
even though (3 * 2)-9 < — ► 3.725£~09 

— ^Trigonometric Functions 

R*-AOB This is a family of related functions. The integer ^4 selects the family member. 
See Table A.2 for details. 

-Mixed Functions 

The real power (and uniqueness) of APL is contained in the mixed primitive functions. The 
mixed functions deal with, and are defined on, arrays as a whole and not element by ele- 
ment. Their results have shapes which often differ from the shapes of their arguments. The 
mixed functions are not generally arithmetic in nature. 

The mixed functions are shown in Table A.4. 

R*-pB (Shape) pB is the shape vector of the array B. 

R*-^ (Ravel) ,B is the vector whose elements are those of B taken by indexing se- 
quence (that is, with the last index varying most rapidly). If is a scalar, ,B is 
the vector whose sole element is B. If J5 is a vector, ,B is identical to B. 

R *-ApB (Reshape) ApB is an array of shape yA whose elements are taken sequentially 
from ,B repeated cyclically as required . A must be a nonnegative integer scalar 
or vector, or an empty vector. (iO)pB is the scalar (,B)[1]. 

R*-^B 
R<-eB 
R^<i>[V\B 

R <-© IV\B Reverse <!) B is an array identical to B except that the elements along the last axis 
are in reversed order. If £ is a vector, then $ B turns B end for end. 

The function © is identical to except that the relevant axis is the first, not the 
last. 



The axis operator (see Operators) can be applied to either <!) or© to designate 
the relevant axis. 
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R<-A(t>B 
R*-AeB 
R<-A(\>IV]B 

R*-Ae [ V]B (Rotate) If ^4 is an integer scalar or one-element vector and B is a vector, then 
A<t> Bis a vector identical to B except that if /I > then the elements ofB have 
been rotated cyclically left A places. 1{A<0 the rotation is to the right \A 
places. 

For higher dimensional arrays the shape of A must be lipB and then each 
element of ^ specifies the amount to rotate the corresponding vector along the 
last axis of B. 

For example, 

M<—*A BCD 
E F G H 
I J K L 

\ ~\ <^ M B C D A 

E F G H 
L I J K 

As in the monadic case, the function e is identical to cl) except that the relevant 
axis is the first, not the last. The axis operator (see Operators) can be applied to 
either (1) ore to designate the relevant axis. 

R*-A.B 

R*-A , [ V\B (Catenate) This function is used for gluing together two arrays to form a larger 
array. 

If A and B are vectors (or scalars), A,B is the vector whose elements are those 
of A followed by those of B. 

Matrices are catenated along the last axis of each by imagining them to be writ- 
ten side by side and then glued together along the adjacent sides. (The last axis 
is the one which is extended.) Obviously only the first dimension of each must 
match. 

The same idea extends to higher dimensional arrays. For example, a 3X4X5 
array may be catenated to a 3X4X2 array of the same type to form a 3X4X7 
array. 
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Arguments which differ in rank by 1 are also permitted, so that for instance a 
vector may be catenated to a matrix by treating the vector as if it were an n X 1 
matrix. Again this concept extends to higher dimensional arrays, so that a 3 X4 
array may be catenated to a 3X4X5 array to form a 3X4X6 array. 

The axis operator (see Operators) can be applied to catenate to designate some 
axis other than the last as the axis to be extended. The axis number Kmust 
designate one of the axes of the higher rank argument. For example, if the in- 
dex origin is 1 , and A and B are matrices, then A, [2]B is equivalent to A.B, and 
corresponds to gluing the bottom edge of A to the top edge of B. 

Unless one of the arrays is empty they must be of the same type, i.e., both 
numeric or both character. 

A scalar argument is extended as necessary. 

R*-A,IV\B (Laminate) Lamination is analogous to gluing two essentially 2-dimensional 
sheets of wood together to form a 3-dimensional board. 

In APL we can join two identically shaped (say 5X7) matrices together to form 
a 3-dimensional result. The new axis of the result will have length 2, but we 
have a choice where we locate it in the new array. We can have the result of 
shape 2X5 X7 or 5 X2X7 or 5X7X2 depending on whether we put the new axis 
before the first of the original ones, between the first and second, or after the 
second. 

If V is not an integer then R*-A,IV]B specifies that A and B are to be 
laminated, not catenated. And the value of V relative to the original axis 
numbers specifies where the new axis is to go. Thus if the index origin is 1 , the 
A and B are 5X7 matrices, then ^,[0.5]B is 2X5X7, A,[l.5]B is 5X2X7 and 
R'^-y4,[2.5]B is 5X7X2. Inthelastcase, for example, < — ►^andi?[;;2] 
■« — »5. 

The exact value of V doesn't matter, only where it stands relative to the 
original axis numbers. 

Both arguments must be of the same shape unless one is a scalar, in which case 
it is extended. Both arguments must be the same type (numeric or character) 
unless they are empty. 
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R QB (Dyadic Transpose) This function provides a way of permuting the axes of an 
array (and also of obtaining diagonal sections of an array). 

Suppose £ is a 3-dimensional array and we wish to form from it the 
3-dimensional array/? such that =BIK-J;J\ for all values of K, /and / 

that are valid subscripts forfl. In^PZ, this is expressed/? «-3 1 2 Sfi. Theleft 
argument of S is found by inspecting the subscripts K\I;Joi B in the equation 
defining/?[/;J;A]. The first subscript of fl, i.e.,^r, is the 3rd subscript of/?, the 
second, I, is the first of R and the third, J, is the second of R. Hence 312. 

We can also take a "diagonal section" through an array. For example, we can 
derive from B a 2-dimensional array S such that S[r,J\ =B[/;/;7] . In APL this 
is S<-2 1 2 SB. The rule for finding the left argument is the same as above. 

If S is a matrix then 2 1 QB is the conventional transpose of B and 1 1 Sfi is the 
main diagonal. 

/?<- S)J5 (Transpose) This function reverses the order of the axes of its argument. For- 
mally, < — ippB) S)5. In particular, if £ is a matrix then S)5 is the con- 
ventional transpose of B. 

R^-AIB-.C^.-M 

(Indexing) Elements may be selected from an array y4 to form a new array/? by 
means of an index expression in square brackets. An index expression for an n- 
dimensional array ^4 is a list of n expressions separated by semicolons. The 
value of each expression must be an array (e.g., B) each of those elements is a 
permissible index along the corresponding axis of A. Each indexing array may 
be of any rank, although scalars and vectors are the most common. 

Any of the constituent expressions of an index expression may be omitted en- 
tirely; its value is taken to be the entire index vector for that axis of A. 

The shape of R is the catenation of the shapes of the indexing arrays. In par- 
ticular if y4 is a vector then the shape of ^ [B] is the shape of B. Technically, for 
higher rank index arrays, 

AIB;C,... J)\ — » {(j>B),{pC),...,{pD))pA{{MA,Q-,----,{m 

The use of a pair of symbols, [ and ] and what amounts to a vector of arrays as 
one of its arguments, distinguishes indexing as an exception to theylPX syntax 
rules. Nevertheless indexing is still conceptually a dyadic function of an array 
and an index. 
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A[B;C;...J}]*-R 

(Indexed assignment) An indexed subset of the elements of an existing array ^4 
may be replaced by the elements of the array R. 

[B;C;...;D] must be a valid index expression for A and the shape of 
A[B;C;...;D] must match the shape of R, except that axes of length 1 are ig- 
nored. 

If is a one element array of any rank, it is extended as necessary. 

A and R must be of the same type unless the index expression selects no 
elements of A. 

R *-A \B (Take) This function selects elements from the beginning or end of a vector B 
and it can also be used to "pad" B out to a given length with zeros (if B is 
numeric) or blanks (if B is character). In general it can be thought of as selec- 
ting a "comer" of an array B. 

A must be an integer scalar or vector, or an empty vector. B can be an array. 
Unless B is a scalar, there must be one element of ^4 corresponding to each axis 
ofB. 

The shape of ^4 tB is the vector whose elements are the absolute values of those 
oiA that is \,A. 

If S is a vector (and therefore^ is a scalar or a one element vector) then there 
are four cases. 

(a) {pB) <A. RisB catenated with (pB)—A zeros (or blanks). 

(b) (0 ^A)^^A <pB). /? is a vector of the first A elements of B. 

(c) ({-pB)<A)/\(A < 0). Risa vector of the last \A elements of 
B. 

(d) A < —pB. R is —(A +pB) zeros (or blanks) catenated withB. 
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The following diagram summarizes these cases. 

pad B take \A elements take A elements pad B 

on left from end of B from beginning of B on right 
_^ ^ + > 

pB pB A 



If J3 is of higher rank then each of the axes is treated as in the vector case, using 
the corresponding element of A. 

R*-A\rB (Drop) This function is a variant of take. It also selects a "corner" of the array 
B but it does it by deleting rows and columns rather than by keeping them. 

The conditions on A and B are the same as for take. 

If £ is a vector there are four cases as illustrated in the following diagram. 



drop all drop \A elements drop A elements drop all 

of B from end of B from beginning of 5 of B 
_^ ^ ^ > 

pB pB A 



If B is of higher rank then each of the axes is treated as in the vector case, using 
the corresponding element of A. 

R*-A/B 

R^A+B 

R^-A/mB 

R*-A-f-[V\B (Compress) This function provides selection based on a boolean vector A of 
I'sandO's. 

B may be any array and ^4 is a boolean scalar or vector, or an empty vector. 

A scalar or one element vector /I is extended to conform to B and a scalar B is 
extended to a vector conforming to A. 

The number of elements of A (after extension) must equal the length of the last 
axis of B (after extension). 

If B is a vector, the A/B is the vector consisting of those elements of B cor- 
responding to the I's in v4. It follows that the length of ^4/5 is the number of 1 's 
in A. 



If B is of higher rank, then the compression is applied to the vectors along its 
last axis. 
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A+B is identical XoA/B except that the compression is applied to the first axis, 
not the last. 

The axis operator (see Operators) can be applied to either / or to designate 
the relevant axis. 

R^A^ 
R*-A \ IV]B 

i?<-y4-»r[F]B (Expand) This function opens out the array B by inserting zeros (or blanks) 
based on the boolean vector A. It is a partial inverse to compression in the 
sense that A/A \B< — > B. 

B may be any array and ^ is a boolean scalar or vector, or an empty vector. 

A scalar B is extended to a vector of length equal to the number of 1 's in yl. 

The number of I's in^ must equal the length of the last axis of B (after exten- 
sion). 

If £ is a vector, then v4 \Bis the vector whose length is that of A and consisting 
of the elements of B placed in order wherever A has 1 's and zeros ( or blanks) 
wherever v4 has O's. 

If B is of higher rank then the expansion is applied to the vectors along its last 
axis. 

A-^B is identical to ^ \ B except that the expansion is applied to the first axis 
instead of the last. 

The axis operator (see Operators) can be applied to either \ or -V to designate 
the relevant axis. 

R*-iB (Index generator) t5 is a vector of B consecutive ascending integers, the first of 
which is the current index origin. 

B must be a nonnegative integer scalar or other one element array. 



lO is a common expression yielding an empty numeric vector. 
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(Index of) y4(B is a "search" function which finds the first occurrence in^ of 
each element of S. 

A can be any vector. B can be any array. AiB has the same shape as B. 

If J5 is a scalar then /I tB is the index (relative to the current index origin) of the 
first occurrence of B in ^4 . If 5 doesn't occur in ^4 at all, then v4iB is DIO+pA 
(i.e., the first index beyond the range of A). 

If S is an array of higher rank then each element of y4iB is the least index in^ of 
the corresponding element of B. 

This function is obviously index origin dependent. 

The equality test implied in this function uses the comparison tolerance for 
numeric arguments. 

(Member oO A and B can be any arrays. AeB is a boolean array the same shape 
as A. Each element of AeB is 1 if the corresponding element of ^ occurs any- 
where in B, and otherwise. 

The equality test implied in this function uses the comparison tolerance for 
numeric arguments. 

(Grade up) A "sorting" function. B may be any numeric vector. ^ B has the 
same shape as B. 

^B is the permutation of ipB such that B[/^ B] is in nondecreasing order. The 
indices of any set of identical elements of B occur in ^ B in ascending order. 

Since ipB is index origin dependent, so is ^B. Comparison tolerance is not 
used in the comparisons. 

(Grade down) B may be any numeric vector. ^ B has the same shape as B. 

^ 5 is the permutation of ipB such that Bl^ B] is in nonascending order. The 
indices of any set of identical elements of B occur in ^ B in ascending order. 

Since ipB is index origin dependent, so is ^B. Comparison tolerance is not 
used in the comparisons. 
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R*-A7B (Deal) A random function. A andS are nonnegative integer scalars or one ele- 
ment arrays, and A^B. 

A7B is a vector of length^ , obtained by making ^4 random selections, without 
replacement, from the population iB. 

Since iB is index origin dependent, so is A7B. The system's random link 
parameter is used implicitly. 

R*-ASB (Matrix divide) This function is useful in numerical work for solving systems 
of linear equations, least-squares fitting problems and problems involving 
projections of vectors in n-space. 

A and B are numeric arrays of rank 0, 1 or 2. Scalars and vectors are shaped in- 
to one column matrices. The (reshaped) arguments must both have the same 
number of rows, and the columns of (the reshaped) B must be linearly indepen- 
dent. (The latter implies in particular that B cannot have more columns than 
rows.) 

The definition of ASB is deceptively brief: the shape of ASB is (llpA),(lipB) 
and the value of ABB is such that +/ ,iA-B+ .XASB) * 2 is minimized. 

In particular if £ is a square, nonsingular matrix then the minimum referred to 
is zero and B+.X(A SB) * — ►y4.If^isa vector then A SB is the vector solv- 
ing the set of linear equations B+.XX< — *A. If A is a matrix then A SB gives 
the solution of the set of equations for each column of A. 

It can be seen from the definition that if £ is a rectangular matrix then ASB 
gives the linear combination of the columns of B which most closely (in the 
least-squares sense) matches ^. This can be used in linear regression for curve 
fitting, and in vector projection problems. 

R*-SB (Matrix inverse) is a numeric array of rank 0, 1 or 2. A scalar or vector is 
reshaped into a one column matrix. The columns of the (reshaped) argument 
B' must be linearly independent. (In particular, B' cannot have more columns 
than rows.) 

If Nis the number of rows of the reshaped argument B' and /is aniVX A/^identi- 
ty matrix then SB* — ^ISB', except that if fi is a scalar or vector then the result 
is reshaped to a scalar or vector respectively. 
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R*-ALB (Decode, or base value) This function is used to convert a coded representa- 
tion, B, of a number into the number itself, according to the coding scheme or 
radix^. This is one of the essential operations in number system conversions. 



If ^ and B are vectors of equal length then AlB is a scalar equal to +/WXB 
where Wis a weight vector corresponding to the radix y4; W*-<t> X\<\>llA,l- 
For example if +— ♦ 3 5 7 then FT*— * 35 7 1 , and 3 5 712 3 5 -«— ► +/35 7 1 X2 
3 5-«— ► +/70 215*— »96. 

A scalar or one element vector argument is extended to conform to the other 
argument. Thus2il011 •^-►2222110 ll"-- +/8421X101 l-^-ll. 
("The base 2 value of 1 11 is 11.") 

In the case of arguments of higher rank, each radix vector along the last axis of 
A is appUed to each representation vector along the first axis of B, in accor- 
dance with the above algorithm. The shape of AlB is ( 1 ipA),{l itB). 



R *-AlB (Encode, or representation) This function converts a number B into an encod- 
ed representation according to the coding scheme or radix^. This is one of the 
essential operations in number system conversions. 



Encode is a partial inverse of decode. For example 3 5 7T96 ♦--♦235 while 3 5 
7i23 5*— *96. 

If >1 is a vector and fi is a scalar then AJB is equivalent to the following pro- 
gram. The index origin is assumed to be 1 and comparison tolerance is 0. 



VR"- A ENCODE B J 



[11 
[2] 
[3] 
[4] 
[5] 
[61 
[71 
[8] 
[9] 



R*-OXA 

I^pA 

REPEAT: 



RO- VECTOR.SAME SHAPE AS A 



-(/=0)/0 

Rm^A[I\\B 

-*(A[I\=Q)/Q 

B*-(,B-R[l\)^A[l\ 

I*-I-l 

-^REPEAT 

V 



PiREMEMBER: 0\B*—*B 



UA is a scalar then ^T5< — *A\B. 
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In the case of higher rank arrays, each vector along the first axis of is applied 
to obtain the representation of each element of B, the resulting representations 
being arrayed along the first axis of the result. That is, 

v4[;/;...;/nT5[L;...;iV]— */?[;7;...;/j:;L;...;Nl 

for all values of J,...K,L,.. .JVwhkh are valid indices for yl and B. 

The shape of ATB is (pA),(pB). 

<SiA 

R*-^A (Execute) This function executes the APL statement represented by the 
character vector (or scalar) yl. The value of 35^4 is the value of the statement, if 
it has one. If the execution of A evokes an error report then the report of the 
type of error will be preceded by 2!. A system command is not an APL state- 
ment and cannot be executed with (D. 

Two common uses for execute are (a) passing object names, including func- 
tion names, as arguments to functions, with later evaluation, and (b) conver- 
ting character representations of numbers, obtained from a file, for example, 
to numeric form. 

Execute can make programs difficult to analyze or understand. It should be 
used with restraint. 

R*-WB (Format) B may be any array. The result of this function is a character array 
which, if displayed, would have the same appearance as if S itself were 
displayed. 

The system's printing precision parameter (see DPP) is used implicitly for for- 
mat, but the printing width (see OPW) is not: format acts as though the print- 
ing width were infinite. 

Format does not alter a character array argument. 

For a numeric argument, the shape of ^B is the same as the shape of B except 
for the last dimension. A scalar £ is an exception: it is treated as a one element 
vector. 

Format is useful for mixing character and numeric data on one output display 
line, and for converting data to be sent to an external file or device such as a 
printer. 
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R*-A^B (Dyadic format) This function is similar in purpose to monadic format, but it 
uses variations in the left argiunent to provide progressively more detailed 
control over the result. 

B may be any numeric array. ^4 is an integer scalar or vector. 

In general a pair of numbers is used to control the result. The first determines 
the total width of a ntmiber field and the second controls the precision. 

If the precision indicator is negative then E-format is used and the magnitude 
of the precision indicator is the number of digits in the multipUer. If the preci- 
sion indicator is nonnegative then regular decimal form is used and the value 
of the indicator specifies the number of digits to the right of the decimal point. 

If the width indicator is zero, a Held width is chosen such that at least one space 
will be left between adjacent numbers. 

If ^ is a scalar or a one element vector it is treated like a number pair with a 
width indicator of zero. 

If is a two element vector, it provides the width and precision for the entire 
array B. 

Otherwise A must be a vector with a pair of elements (width, precision) for 
each index along the last axis of B. 

-Operators 

Operators in APL provide a means of modifying some of the primitive functions or of 
creating whole families of new functions. 

Although in many contexts the terms "function" and "operator" are used more or less 
synonymously, in APL they have quite distinct meanings. "Function" is used for things 
such as + or S which take arrays as arguments and produce arrays as results. "Operator" is 
used for a special kind of function which takes functions and/or arrays as arguments and 
produces a derived function as a result. 

Reduction, scan, inner product, outer product and axis are the five operators available in 
MicroAPL. 
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R*-f/B 

R*-f-/-B 

R*-f/[y]B 

R*-f-/-lV]B (Reduction) NOTE: The symbol for the reduction operator is /. f/ is the 
mixed monadic function derived by applying reduction to any scalar dyadic 
primitive function f. R*-f/B is the syntax of the derived function. 

The definition of f/B is as follows. 

(a) If B is a scalar, f/B< — >B. 

(b) If fi is a 0-element vector, then f/5 is the "identity element" for f, as 
shown in Table A. 3. If no identity element exists a domain error is evoked. 

(c) If £ is a 1-element vector then f/B is the scalar (iO)pB. 

(d) Iffi is a vector of length 2 or more, thenf/S < — >B[l] fB[2] f...f BIpB]. 

(e) If B is an array of higher rank , the reduction rules (b) - (d) are applied to 
the vectors along the last axis of B. The shape of f/B is lipB. 

f-/- is identical to f/ except that the reduction is applied along the first axis in- 
stead of the last. 

The axis operator can be applied to the derived function f/ or f-/- to designate 
the relevant axis. 

Some common reductions are 

+/ sum of 

X/ product of 

r/ maximum of 

L/ minimum of 

A/ "for every" 

V/ "there exists" 

W parity check 
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R'>-{\IV\B 
R'>-fMy\B 

(Scan) NOTE: The symbol for the scan operator is \ . f \ is the mixed 
monadic function derived by applying scan to any scalar dyadic primitive 
function f . /? <- f \ B is the syntax of the derived function. 

The definition of f \B is as follows. 

(a) I f ^ is a scalar or a 0-element vector, f\B *--* B. 

(b) If fl is a vector of length lor more then for every scalar leipB, (f \ 5) [7] <- -+ 
f/B[iI]. 

(c) If B is an array of higher rank, the scan rules (a) and (b) are applied to the 
vectors along the last axis of B. 

The shape of f \ B is the shape ofB.f-f- is identical to f \ except that the scan is 
applied along the first axis instead of the last. 

The axis operator can be applied to the derived function f \ or f-*r to designate 
the relevant axis. 

R'^-i/mB 

R^f+[V\B 

R^i\[V\B 

i?'«-f^[F]B 

R<^e[V\B 

R<^<^[V\B 

R*-A^ {V\B 

R^A/[V\B 

R^A\[V\B 

R*-A,[V\B (Axis) The axis operator, designated by the pair of symbols [ and ] , takes an 
axis value Kand modifies the function to the left, usually by designating a rele- 
vant axis of one of its arguments. 

In all cases Kmust be a numeric scalar or 1-element vector. 



Since axes are numbered relative to the current index origin, the axis value Fis 
origin dependent. 
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R*-Af.gB (Inner product) Inner product derives a new dyadic mixed function f.g from 
any two dyadic scalar primitive functions f and g. 

If A and B are vectors of the same length, or they are both scalars, thenylf.gi? 
•^^ f/AgB. 

In general, if A and B are arrays other than scalars, and ( ItpA) = (ItpB) , 
then the shape ofAf.gB is (~1 lpA),(l IpB) and (^f .gS) [/; . ..;J;L;.. . < — ► 
f /A[r,...iJ;] g B [;/,;.. .;A0 for all valid sets of indices. 

Finally if either one of y4 or B is a scalar , or if either is a I-element vector, it is 
reshaped into a vector whose length satisHes the general case above. 

The inner product +.X is the ordinary "matrix product." Other common in- 
ner products are A. = , +.= , L.+ , r.+ ,and X.*. 

R*-AO.gB (Outer product) Outer product derives a new dyadic mixed functionO.g from a 
dyadic scalar primitive function g. 

The shape ofAO.gB is (pA),(pB) and (^o.gB)[/; . . . ;/;£,;.. .-Ml* — * All;...; Jig 
B[L;...;M] for all valid sets of indices. (Ify4 or Bis a scalar, the index expres- 
sion is omitted.) 
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System Variables and System Functions 



System variables and system functions provide facilities for communicating with the APL 
System. Unlike system commands they can be used within APL expressions. 

System names are distinguished: they all start with □ or □. 

System variables and functions are always in your workspace, but they do not appear in 
)FNS and ) VARS lists. They cannot (and need not) be copied or erased. Some of them can 
usefully be localized in function deOnitions: DIO is the most common example. 

The difference between system variables and system functions is mainly a matter of their 
syntax. 



System Variables 

System variables are best viewed as variables which you share with the APL system. You 
can't do anything to or with a system variable without the system taking some notice. 

When you use a system variable in an expression the system generates and supplies the 
value. For example HWA returns the working area available, but the system has to do a 
storage reorganization and cleanup to get that value. 
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Conversely, when the value of a system variable is specified, the system may automatical- 
ly adjust one of its internal parameters. For example DIO*-0 results in the internal index 
origin parameter being set to 0. Often there is a Umited set of acceptable values for an inter- 
nal parameter, and the system will appear to ignore an attempt to give the corresponding 
system variable an unacceptable value. 



DCT Comparison tolerance. Controls the internal comparison tolerance 
parameter. Acceptable values: through IE ^5. Value in a clear workspace: 
1£^8. 



niO Index origin. Controls the internal index origin parameter, which is used in in- 

dexing, the axis operator, DFX.l, dyadic S,4 ,t and i. It is the index of the 
first element of any nonempty vector. Acceptable values: or 1. Value in a 
clear workspace: 1. 

DLX Latent expression. When a workspace is loaded, CILX is executed. Value in a 
clear workspace: an empty vector. 

nPP Printing precision. Controls the parameter which determines the number of 
significant digits in the output representations of numeric APL arrays. Accep- 
table values: integers 1 through 11. Value in a clear workspace: 8. 

nPW Printing width. Controls the parameter which is the maximum width of aline. 

Affects all output except bare output (□). Acceptable values: integers 24 
through 80. Value in a clear workspace: 80. 



URL Random link. Used in roll and deal(?). Acceptable values: integers 1 through 
32767. 



DA V Atomic vector. A 256 element vector of the bytes whose hexadecimal represen- 
tations are $00,$01,...,$FF in ascending order. Thus, in origin 1, IIL4 F[17] is 
equivalent to $10. The elements of character variables are all elements of Q<4 V 
and any element of (IL4 Kcan be used in a character variable. The value of 
CL4 Fcannot be altered. 



ULC 



Line counter. A vector of the line numbers of active functions, most recently 
initiated first. OLC cannot be altered by assigning values to it. 
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□rc Terminal control. An 8 element character vector whose elements have the 
following effects when output to the sCTeen. 



OTCll] 


move cursor left 


□rc[2] 


move cursor right 


□rci3i 


move cursor down 


DTC[4] 


move cursor up 


DTCIS] 


clear screen and home cursor 


□rc[6] 


home cursor to top left hand comer 


DTCm 


RETURN (" new Une") 


□rc[8] 


Erase to end of Une 



nxC cannot be altered. 



OTS Timestamp. Used for setting and reading the internal system clock. A six ele- 

ment integer vector representing the date and time as follows: 
□rS[l] Last two digits only of the year 
□rS[2] Month (1 through 12) 

□rsi3] Day (1 through 31, consistent with month and year) 
□rS[4] Hour (0 through 23) 
□rS[5] Minute (0 through 59) 
□rS[6] Second (0 through 59) 

Acceptable values: representations of valid dates and times in the above for- 
mat. 

DTS may be set at any time. The system will then keep its clock up to date. 
The system clock is not kept in the workspace, so loading a new workspace 
does not affect it. 

□ WA Working area. Available space in the active workspace in bytes. □ WA cannot 

be changed by assigning it a value. 

□ Evaluated Input/Formatted Output. When □ is assigned a value, the system 
displays a representation of the value on the screen. ClPPand DPffaffect the 
display. A vector which cannot be displayed within the printmg width is con- 
tinued, indented on subsequent lines. Rows of a matrix are displayed as 
separate vectors. One line is skipped between the matrices of a 3-dimensional 
array, two lines between 3-dimensional subarrays and so on. £ format is used 
automatically when necessary for numeric arrays. 
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When a value for □ is required, the system generates its value by obtaining it 
from the user: a prompt (□:) is displayed and the user must enter an expression 
to be evaluated, or (see "Punt"). The value of the expression is the value of 
□, 

□ Character Input/Bare Output. When □ is assigned a character scalar or vector 

value, the system sends the characters to the screen in a continuous stream 
without gratuitous newline characters. This is useful and often necessary when 
you wish to display long strings containing cursor positioning characters (see 

arc). 

When a value for □ is required, the system generates the value as it does for 
□ except that (a) there is no prompt: the cursor simply remains where it is, and 
(b) the input is taken as a vector of characters and is not evaluated. Trailing 
blanks are trimmed off and the result is always a (character) vector. 

Program function key 2 (i.e., shifted "2" on the numeric keypad), as a 
response to □ or □ input, is equivalent to a "punt." 

NOTE: Because a machine awaiting character input looks just the same as a 
machine locked in a long calculation (the cursor is at the left margin) , it is good 
practice to include your own prompt in your programs. □ output followed 
directly by □ input is a neat way of doing this on one screen line. 



System Functions 

OCR F Canonical representation. F is a character vector (or scalar) naming a func- 
tion. The result is a character matrix containing a representation of the func- 
tion. The representation is similar to that displayed by the V — editor, but 
without V ' s or line numbers. The result is of shape if Fdoes not denote an 
existing function. 

HDL S Delay. S is a positive integer scalar. This function takes S seconds to complete. 
The result is the length of the delay, namely S. 

OEX A Expunge. ^4 is a character scalar, vector or matrix. Any variables or functions 
named by the rows of A are erased, if possible. The explicit result is a boolean 
vector whose th element is 1 if the /" th row of ^ denotes a name which is now 
available for use, whether or not an object by that name was erased. 



84 



Chapter? 



DFX M Fix. Mis a character matrix representing a function definition in the same for- 
mat as the result of UCR. QFA^estabUshes the definition if possible. The ex- 
plicit result is a character vector naming the function estabUshed, or else the in- 
dex (relative to the current index origin) of the first row of Mcontaining a fault 
which prevented estabUshment. The name of the intended function cannot be 
in use, except as a function name. 

□M7 A Name classification. Aisz. character scalar, vector or matrix. The result is a 
vector of name classifications giving the usage of the character sequences in 
each row of A 



0: a name available for usage 
1: a label 

2: a variable name 

3: a defined function name 

4: other (a distinguished name, or not a name) 



K Name list, ^is a numeric scalar or vector with elements 1 , 2 or 3. The result is a 
character matrix whose rows name the objects in the indicated classes which 
exist in the active workspace: 1 , 2 or 3 for labels, variables or functions, respec- 
tively. 

L DNL K Name list. L is a character vector or scalar. The result is like that of monadic 
UNL but the Ust contains only names beginning with one of the letters in L. 



nSTOP F Fis a character (scalar or) vector naming a function. The result is an integer 
vector of line numbers on which "stops" have been placed. 

NDSTOPF 

F is a character (scalar or) vector naming a function. iV is a vector of line 
numbers. "Stops" are set on the lines of the named function whose numbers 
appear in TV (See Stop Control for the effect of a stop). An empty vector N 
removes all stops. Editing a function removes all its stops. 

NOTRACEF 

DTRACEF Simnai to DSTOPbut for "traces" instead of "stops." 

HLOAD W Wisa character vector naming a workspace. HLOAD is identical to )LOAD 
but it may be executed as an APL statement. 
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DPEEK V Fis either (a), a scalar or vector of integers defining machine addresses, or (b), 
a 2-column matrix of integers whose rows define ranges of machine addresses. 
The ranges are inclusive. 

The result is a character vector (i.e., of elements of Q<4 V) containing the 
current contents of the machine addresses defined by V. 

N.B. The machine addresses are interpreted as in origin 0, regardless of the 
current index origin. 



Examples 



(1) UPEEK is the current contents of hexadecimal location 0000. The only 
reUable way to "see" the value is to look it up in 1114 V: CU ViOPEEK pro- 
duces an integer result in the current index origin. 

(2) OPEEK 32768 32769 is the contents of the first 2 locations on the screen 
(Hexadecunal 8000-8001). 

(3) DPEEK 1 2 p32768+0 1999 is the entire screen. (Hex 8000 - 87CF). 
CnPOKEV 

V is a scalar, vector or range matrix, as in DPEEK. C is a character vector 
whose length is consistent with V. A scalar Cis extended to be consistent with 
V. 



Example DAVDPOKE 1 2p32768-l-0 255 will show the result of storing all 
possible byte values into screen memory. 

NOTE: It is sometimes important to know that the assignment of bytes to ad- 
dresses occurs "from left to right" in DPOKE. 

DSYSC 

A DSYS C Execute 6809 machine code. The machine code (i.e., instructions) contained 
in, or pointed to by, C is executed. 

Cis either 

(1) a scalar or one element vector integer between and 65535, representing 
the machine address at which execution is to begin, or 

(2) a character (scalar or) vector of bytes to execute directly. 
Control is returned to APL by executing a 6809 RTS instruction. 



86 



Chapter? 



The explicit result of OSYS is an integer scalar representing the value of the 
6809 D register at the time of returning. 

A is an optional parameter list. If present it must be a (scalar or) vector of in- 
tegers between and 65535. The two-byte value represented by the first ele- 
ment of A is placed in the 6809 D register before execution begins, and the re- 
maining elements are placed on the stack (two stack bytes for each element). 
The top pair of bytes on the stack contain the return address (i.e., of APL's 
□SyShandler). Thesecond pair correspond to>l[2], thethird pair to/l[3] and 
so on. In each pair the low order byte is stacked first. 

The stack may be used by the machine language routine, but it must be left in 
this same condition again when the RTS instruction is executed to return to 
APL. 

nXR C External representation. Translates APL characters to ' 'APL-ASCll Overlay 
(Typewriter-Pairing)" representation. C is a (scalar or) vector of APL 
characters or elements of OTC. The result is a character vector formed by 
catenating the representations of the elements of C according to the APL- 
ASCll typewriter pairing convention (see appendix). Overstruck elements of 
C are expanded into the two constituent characters separated by a backspace 
character. 

niR C Internal representation. OIR and DXR are strict inverses except that HIR will 
handle either of the two possible permutations corresponding to the 
overstruck symbols. 



There are more system functions in MicroAPL. These all concern files and are included in 
a subsequent chapter. 
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Errors 



If an error is detected in the execution of a statement, an error report is displayed. Tliis 
report consists of an error message followed by a display of the statement. The point at 
which execution was interrupted is marked by a caret (A). Any implicit results, such as 
variables having been assigned values, which occurred before the point of error, remain in 
effect. 



Error Messages 

SYNTAXERROR 

A line of APL characters is not a valid statement. 

VALUEERROR 

An expression with no value occurs in a context requiring a value. The use of a 
variable before it has been assigned a value is a common cause of this error. 

DOMAINERROR 

The argument or arguments of a primitive function are not within its domain 
of definition. Generally speaking, /l4iV/(randL£7VGraf errors are recognized 
first if possible. 
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RANKERROR 

The rank of an argument of a function does not meet the requirements of the 
function, or the ranks of the left and right arguments do not conform. 

LENGTHERROR 

The argument ranks conform, but the sizes of one or more axes do not. 

INDEXERROR 

(1) The value of an index expression is an invalid index for the associated ar- 
ray. (2) An invaUd axis number is specified in an axis operator. 

CHAR ERROR 

Certain keys are invalid in APL and evoke a character error report when 
struck. 

SYMBOL TABLE FULL 

Too many names have been used. Save the workspace; clear and copy the en- 
tire workspace. (The symbol table size may be changed in a clear workspace 
with the )SYMBOLS command.) 

WSFULL 

Out of memory. Clear the state indicator by executing -+ sufficiently many 
times. Erase unnecessary objects. 

SYSTEMERROR 

Fault detected in the APL system. 

DEFNERROR 

This error is dealt with in the chapter on defined functions. 
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FUes 



A file in the APL system is viewed as a collection of items external to the APL workspace. 
These files can be created, added to, retrieved from, erased and renamed through the use of 
special ^PL system functions. 

There are four types of files: 

a) y4PZ,-sequential 

b) BARE-sequential 

c) Relative 

d) Program 

An^lPL-sequential file is simply a sequence of APL values of any shape, rank and type. 

A BARE-sequential file is a sequence of 8-bit binary characters. 

A Relative file is a sequence of 8-bit binary characters which are organized into fixed sized 
groups called 'records' which may be accessed in random order. 

A Program file is a special kind of BARE-sequential file normally used to contain pro- 
grams and workspaces. As such, it is not usually accessed with the techniques discussed in 
this chapter. 
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General Concepts: 

Files reside on some external medium and are identifled by a name. Filenames are con- 
structed according to specific rules described below. 

In order for the data in a file to be available to a workspace, it must be "tied" to the 
workspace with a tie-number. Information is transferred to and from the file using this 
□umber. When access is not required by the workspace, the file can be "untied." 



Filenames: 

The filenames of y4PZ,-sequential and BARE-sequential files are composed of any combina- 
tion of letters and numbers (see Systems Overview Manual) (e.g. , the name of a disk file can 
contain up to 15 characters). The following are valid filenames for sequential files: 

GEORGE 

INVENTORY.NOV 
SALES004 

The filenames of Relative files are somewhat more detailed than those of sequential flies. 
The basic filename is formed by following the same rules as above. However, special addi- 
tions are also required in the name. The meaning of the special sequences are described later 
in the section titled "Relative Files." The following are valid names for Relative files: 

V ~ i45^GEORGE,REL 

V ~ iSOAlNVENTOR Y.NOV.REL 

V ~ (200AS/1Z,£S004,/?£'L 



Replies: 

The file operations described in the rest of this chapter frequently return replies which 
reflect the result of the operation. The reply is in the form of a character vector which con- 
tains text describing any abnormal condition encountered. If the operation was successful, 
the reply is an empty vector. 



FILES 
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General File Manipulation Functions: 



REPLY ^ FNUCREATEN 

FNi% a character vector containing the name of a file which is to be created. If a 
file with the same name already exists, it is replaced. The argument TV is an in- 
teger scalar specifying the "tie-number" to be used. Output operations such as 
□ WRITE or UPUTaxe valid. 

REPLY*- FNUTIEN 

This function is used to access an existing file. The file specified by FN is 
located and attached to the workspace with the tie-number given by the integer 
scalar N. Only input operations such as HREAD or DG^r are valid on a file 
accessed in this manner. 

REPL Y<-FN DAPPEND N 

This function is used to add items of data to an existing sequential file. The file 
specified by FN is located and attached to the workspace with the tie-number 
defined by the integer scalar N. Only output operations such as □ WRITE or 
DPUTaie valid here. 

REPLY*- FNDUPDATEN 

This function is used to access existing relative files. fiVspecifies a file which is 
located and attached to the workspace with tie number N. Data can be sent to 
and retrieved from the file using the functions DREAD, OGET, UWRITE 
and UPUT. 

nUNTIEN 

The argument N is an integer vector containing tie-numbers of files to be 
released from the workspace. 
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REPLY ■>- FN OERASEN 

The fUe named in FN is erased. N is an integer scalar representing the tie- 
number of the currently tied file to be erased. 

REPLY*- FNURENAMEN 

The argument Nis an integer scalar specifying a currently tied file. This file is 
renamed to the name defined in the argument FN. 

UNUMS 

This function returns a vector of all currently active tie-numbers. Their order 
corresponds to that of the filenames returned by the function HNAMES. 

UNAMES 

This function returns a character array of the names of all currently tied files. 
Their order corresponds to that of the tie-numbers retimied by the function 
UNUMS. 

REPL Y *- DSTA TUS N 

The argument Nisan integer scalar representing a file tie-number. The func- 
tion response reflects the status of the most recent operation performed on the 
file with the specified tie-number. 

Z*-OLIB L Lisa, character vector designating a device (e.g., 'DISK/1'), or an empty vec- 
tor. Z is a character matrix representing the directory for the device. (ASCII 
characters are not necessarily translated to APL.) 



APL Sequential Files 

^PL-sequential files are a sequence of APL values of any shape, rank or type. Such files are 
accessed using DCREA TE. □ TIE. UAPPEND and □ UNTIE. Values are written mto the 
file using □ WRITE and read back into the workspace using UREAD. 

REPL Y*-ZU WRITE N 

Z is any APL variable and N\% an integer scalar. The rank, shape and type of Z 
as well as all of its data are put on the file tied with number N. 



FILES 
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Z- DREAD N 

The 'next' item in the file tied with number Nis read into the workspace and 
assigned to the variable Z. The variable assumes the shape, rank and type of 
the data value from the file. 



BARE-Sequential Files 

BARE-sequential files are a sequence of 8-bit binary values (called bytes). These files are ac- 
cessed using UCREATE, UTIE, DAPPEND and DUNTIE. Bytes are written to the file 
fromy4PZ, character variables using nPUTand read back into the workspace using DGET. 

REPLY ^ ZnPUTN 

The argument Z is a character vector and AT is an integer scalar representing a 
tie number. Character data from the specified vector is written to the file. Each 
byte from the item is transmitted to the file and no additional bytes are added. 

Z ^ DGETNL 

NL is a 2-element integer vector. The first element contains the tie-number of a 
currently tied file. Character data from the file is transmitted to the workspace 
and stored in Z as a character vector. The number of bytes transmitted is 
specified by the second element of NL. If there are too few bytes left in the file, 
only those available will be transmitted. 



Relative Files 

A relative file is composed of "records," each of a fixed size. The record size is defined as 
part of the filename when the file is created (using DCREA TE). This is done by prefixing the 
name with the sequence V ~ (AWA where NN is the desired record length. The name must 
also be suffixed by the sequence, /?£/,. (The cryptic sequence is XhtAPL equivalent of the 
ASCII codes required by the disk system.) 

e.g. , to create a relative file named SAMPLES with records of length 100, use 
the filename 

V - {IQOhSAMPLES.REL 

Relative files are accessed using UCREATE, UTIE, UUPDATE and UUNTIE. Opera- 
tions on relative files are performed on individual records, so DGETand UPUTmnst be 
preceded by the nSEE/ir operation positioning the file-system to a specific record. 
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REPLY *- 



aSEEKNL 



NL is a 2-element integer vector. The first element is the tie-number of a cur- 
rently tied relative file. The file system positions its "current-record" pointer 
to the I'th record in the file where I is specified by the second element of the 
vector NL. If the record does not exist, a reply is returned to that effect. This 
reply can usually be ignored when the file is being written. 



NOTES: 



1 



An attempt to write more characters than will fit on a record will result in an I/O 
ERROR. 



2 



An attempt to read more characters than are on one record will cause characters to 
be read from the next record. 



3 



The maximum record length in a relative file is 254 bytes. 
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Tables of Functions 



Table A.l - Primitive Monadic Scalar Functions 



Symbol Name Definition or Example Page 
Conjugate 

+ or identity +B •• — * 0+B 62 

- Negative -B * — > 0-B 62 

X Signum XB < — ►~lifB<0 62 

B=0 

1 B>0 

■i- Reciprocal -i-B ■> — * l^B 62 

I Floor L3.14~3.14<— » 3"~4 62 

r Ceiling r3.14~3.14 •<— ► 4~3 62 

* Exponential *B* — ► (2.7128...) *5 < — *e*B 62 

* Natural logarithm 9B ■> — ► e®5 62 

Magnitude or 

I absolute value |3.14~3.14 3.14 3.14 62 

* Factorial tO< — ►! 62 

iB*—*BXl{B-l) 
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Symbol Name 



Definition or Example 



Page 



? 

o 



Roll 
Pi times 
Not 



?5 < — ► Random choice from iB 
OB 5X3.14159... 
~0 1 1 



63 
62 
63 



Table A.2 - Primitive Dyadic Scalar Functions 



Symbol Name 



Definition or Example 



Page 



+ 


Plus 


2+3.2 «— » 5.2 


63 


- 


Minus 


2-3.2 -- »• "1.2 


63 


X 


Times 


2X3.2 < — ► 6.4 


63 


.A. 


Divide 


2H-3.2 0.625 


63 


L 


Minimum 


3L7 •^-» 3 


63 


r 


Maximum 


3r7 ■« — ► 7 


63 


* 


Power 


2*3 8 


64 




Logarithm 


y4 ® B « — ► Log B (base A) 


64 






/1®B«— ♦(®fi)^®/l 




1 


Residue 


^5 if^=0 


64 






A\B *—* B-AXLB-^A ifA=^ 




i 


Binomial 


AiB->-^ itB)-r-iiA)XiB-A 


64 




coefficient 


2X5<— ♦lO 3*5— ► 10 


64 






A B AhB AVB AAB AVB 




A 


And 


1 1 


64 


V 


Or 


10 1 1 


64 


A 


Nand 


10 1 1 


64 




Nor 


111 1 


64 


< 


Less 




64 


< 


Not greater 


Result is 1 if the 


64 




Equal 


relation holds, 


64 




Not less 


if it does not: 


64 


> 


Greater 


3<7 ► 1 'A'i^^ <—* 1 


64 




Not equal 


7<3 'B'='B'->—y 1 


64 



Trigonometric 
A R<-AOB 



Restrictions 



Domain Range 



7 tanh5 
6 cosh B 



TABLES OF FUNCTIONS 
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A 


R*-AOB 


Domain 


Range 


5 


sinh B 






4 


(l+fi*2)*.5 






3 


tan 5 






2 


cos B 






1 


sin B 









(1-5*2)*. 5 


B<\ 


0<R 


~l 


arcsin 5 


(|fi)<l 


(|/?)<o--2 


~2 


arccos B 


(|B)<1 


(0</?)A(/?<Ol) 


~3 


arctan B 




(|/?)<o-i-2 


"~4 


0+5*2)*.5 


1<|5 




■~5 


arcsinh B 






~6 


arccosh B 


1<5 




~7 


arctanh B 


(|5)<1 





The angular measure is radians. 

Table A.3 - Identity Elements of Dyadic Scalar Functions 

(see Reduction) 



DYADIC SCALAR FUNCTION 
+ 



X 



I 

r 
* 
« 

o 

/ 

A 
V 
A 
V 

< 

> 



IDENTITY ELEMENT 


1 
1 


The largest representable number. 
Greatest (in magnitude) negative no. 
1 

None 
None 

1 

1 



None 
None 



1 

1 

1 
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A.4 - Table of Mixed Primitive Functions 

In the following table the "syntax" column indicates the highest rank of the arguments. S 
: scalar; V : vector; M : matrix; A : any array. Generally, lower rank arguments are accep- 
table. 



Arrays used in the examples: 

N< — ►34pil2< — *l 2 3 4 
5 6 7 8 
9 10 11 12 
C Ip'ABCDEF ^^AB 
CD 
EF 



Syntax Name 
pA Shape 

VpA Reshape 



Examples 

pC*-- 3 2 

p2 3 5 7 < — ► 4 

p7 < — ► < empty vector > 

3 4ptl2 *—*N 

4pC <—* 'ABCD' 

0p2 3 7 < — ► < empty vector > 

mpC*—* 'A' 



Notes Page 
65 

65 



.A Ravel .N * — ► il2 65 

,7 lp7 

<\iA Reverse ^C* — * BA 1 65 

DC 
FE 

<i;>[\\c*-^ EF 

CD 
AB 

023 5 7 7532 



A<\>A Rotate ' WORDS' 'SWORD' 1 66 

1 21) [lie •«— ♦ CF 
EB 
AD 



TABLES OF FUNCTIONS 



Syntax Name 

A,A Catenate 

A,[V]A Laminate 

VQA Dyadic 

Transpose 

SiA Transpose 

VtA Take 

VIA Drop 

V/A Compress 

V\A Expand 

VIA] Indexing 

MIA-A] 

A[A;...iA] 



Examples 

3 4.7 2 1 3 4 7 2 1 
C/XYZ' < — ► ABX 

CDY 

EFZ 

•CAT,[0.5YDOG' CAT 
DOG 

•CAT, [1. 5]' DOG' CD 
AO 
TG 

p3 12 S(2 3 5pt30) 3 5 2 

1 1 QiV'^-* 1611 

SC < — ► ACE 
BDF 

~2t3 5 7 5 7 
4T2 3 4 » 23 40 

2 ltC«— 

C 

2V EXAMPLE' «— 'AMPLE' 
"~U3 5 7 ♦--3 5 
~2~nC*—* 1 Ip'A' 

1 1/2 3 5-^-25 

1 1/[1]C *—* CD 

EF 

1 10\57— -»570 
101\C*— 

CD 
EF 

'EXAMPLE'14 3 5]*- 
'ABCDEFGHIJKL'[N] 



C[3 2;] £F 



- 'MAF 
* — *ABCD 
EFGH 
IJKL 
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Syntax Name Examples Notes Page 

AIA;...-^]^A 

Indexed CI1;]<— — *C^^PQ 2 69 

assignment CD 

EF 

iS Index t3«— 123 2 71 

generator tO* — ► < empty vector > 

ViA Index of MfiCDVC <— ♦ 3 2,3 72 

•SOUS' CCS' --SI 
'^flCD'iC*-- 12 

34 

55 

/le4 Member of 'C^T^eC-^-*! 1 3 72 

Ct' CABBAGE' ♦—►11 
10 
10 

4kF Gradeup 4i6862«~»4132 2 72 

6862[4i6862]<— 2668 

Gradedown t5 316< — ^4123 2 72 

5316[t53161<— +65 31 

SIS Deal 3?5— ^341 73 
3?5-^-» 145 

BM Matrix H2 2pl 1 1 -^^ 1 "1 73 
inverse 1 

30XB12 5-^-*12 5 
a5<— »0.2 

iWBM Matrix 2 5B2 2pl 1 5 73 

divide 



AlA Decode 1011 8 6 7< — ^1867 74 
24 60 60115 50 lO'^ -57010 



TABLES OF FUNCTIONS 
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Syntax 
ATA 

QiV 



WA 



mA 



Name 
Encode 

Execute 



Examples 

(8p2)T13'^-0 01 101 
24 60 60T56999- - 15 49 59 

«'3+4' --7 

CD 
EF 



Format 



Dyadic 
format 



f^N*—*l 12 
iI55.7~1.2 
^C* — ► C 



'5.7~1.2' 



Notes Page 
74 

75 



5 2iI5(-4-l 2 3)<— *' 1.00 0.50 0.33' 
9~4iI3(H-7)<— '1.429£^01' 
4 205(^3 lpi3)— ♦ 1.00 

0.50 

0.33 



NOTES: 

1 Axis operator is allowed. (Axis is always index origin dependent.) 

2 Index origin dependent. 



75 



76 



3 Comparison tolerance dependent. 
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System Commands, Variables and Functions 



B • 1 - System Commands 


Page 


)LIB 


Report names of saved ws's and files 


42 


)CLEAR 


Activate a clear ws 


42 


ywsiD 


Change or report wsid 


43 


)SAVE 


Save a copy of the active ws 


43 


)LOAD 


Load a copy of a saved ws 


43 


)COPY 


Copy named objects from a saved ws 


43 


)DROP 


Erase a saved ws 


43 


)FNS 


Report names of functions in active ws 


44 


WARS 


Report names of variables in active ws 


44 


)ERASE 


Erase functions or variables in active ws 


44 


)SI 


Display state indicator 


44 


)SINL 


Display state indicator and local names 


44 


)OFF 


Discontinue APL 


44 


)SYMBOLS 


Report or change symbol table size 


44 


)WSLIMIT 


Report or change limit of memory used for ws 


45 



SYSTEM COMMANDS, VARIABLES AND FUNCTIONS 
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B»2 -System Variables Page 

CL4 V Atomic vector 81 

OCT Comparison tolerance 81 

niO Index origin 81 

DLC Line counter 81 

CiLX Latent expression 81 

nPP Printing precision 81 

DPW Printing width 81 

DRL Random link 81 

□rc Terminal control 82 

DTS Timestamp 82 

DWA Working area 82 

□ Evaluated input; formatted output 82 

□ Character input; bare output 83 

B • 3 — System Functions (Non-files) Page 

OCR Canonical representation 83 

DDL Delay 83 

DEX Expunge (erase) 83 

nPX Fix (establish) a function 84 

DNC Name classification for given list 84 

DNL Name list for given classification 84 

UPEEK Read bytes from memory 85 

nPOKE Write bytes into memory 85 

□SYiS Execute machine code 85 

nTRACE Change or report trace settings 84 

nSTOP Change or report stop settings 84 

niR Translate to internal representation 86 

DAT? Translate to external representation 86 

B»4- System Functions (Files) Page 

DLOAD Load ws 84 

DCREA TE Open a file for (re)writing 91 

DAPPEND Open a file for appending 91 

nnE Open a file for reading 91 

□ UPDA TE Open a relative file for update 91 
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B»4-SystemFunctions(Files) Page 

UUNTIE Close file(s) 91 

UERASE Erase a tied file 92 

URENAME Rename a file 92 

□ WRITE Write APL array to file 92 

UREAD Read APL array from file 93 

DPUT Put characters to file 93 

DGET Get characters from file 93 

nSEEK Adjust position in relative file 94 

DSTA TUS Report status of a file 92 

DNAMES Report names of open files 92 

ONUMS Report tie numbers of open files 92 

DLIB Report names of saved ws's and files 92 
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Character Code Tables 



C»l -y4PZ,-ASCII (Typewrite-Pairing) Overlay 





0-* 


1—* 


2— 


3— 


4— 


5— 


6— 


7— 


— 


NULL 


t 









* 





P 


— 1 


HOME 






1 


a 


? 


A 


Q 


—2 


RUN 





) 


2 


i 


P 


B 


R 


—3 


STOP 




< 


3 


n 


r 


C 


S 


—4 


DEL 


e 


< 


4 


L 




D 


T 


—5 


INST 






5 


c 




E 


U 


—6 


EEOL 




> 


6 




u 


F 


V 


—7 


CRFWD 




] 


7 


V 




G 


W 


—8 


CRBCK 




V 


8 


L 


D 


H 


X 


—9 


TAB 




A 


9 


I 


t 


I 


Y 


—A 


CRDWN 


+ 




( 


o 


C 


J 


Z 


—B 


CRUP 


n 




I 


r 


«— 


K 


{ 


—C 


CLEAR 


□ 


f 


f 


□ 


1- 


L 


H 


—D 


CR 




+ 


X 


1 


— » 


M 


} 


—E 


V 


m 






T 




N 


$ 


—F 


A 


I / 




\ 


o 




O 


RUB 



*NOTE: 

These columns contain extensions to the standard ^PL-ASCII typewriter-pairing con- 
vention. 
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C»2 - TERMINAL Character Set 





0— 1— 


2— 


3— 


4— 


5— 


6— 


7— 


— 


NULL 







@ 


P 


c 


P 


— 1 


HOME 


! 


1 


A 


Q 


a 


q 


—2 


RUN 




2 


B 


R 


b 


r 


—3 


STOP 


# 


3 


C 


S 


c 


s 


—4 


DEL 


$ 


4 


D 


T 


d 


t 


—5 


INST 


% 


5 


E 


U 


e 


u 


—6 


EEOL 


& 


6 


F 


V 


f 


V 


—7 


CRFWD 




7 


G 


w 


g 


w 


—8 


CRBCK 


( 


8 


H 


X 


h 


X 


—9 


TAB 


) 


9 


I 


Y 


i 


y 


—A 


CRDWN 


* 




J 


Z 


j 


z 


— B 


CRUP 


+ 


f 


K 


I 


k 


{ 


— C 


CLEAR 


f 


< 


L 


\ 


1 


1 


— D 


CR* 






M 


1 


m 


} 


— E 






> 


N 




n 




— F 




/ 


? 


O 




o 


RUB 



♦ NOTE: 

On output, CR also causes an automatic skip to new-line. 



CHARACTER CODE TABLES 
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C«3— ASCII Character Set 





0— 


1— 


2— 


3— 


4— 


5— 


6— 


7— 


— 


NULL 


DLE 







® 


P 


c 


p 


— 1 


SOH 


DCl 


! 


1 


A 


Q 


a 


q 


—2 


STX 


DC2 


ft 


2 


B 


R 


b 


r 


—3 


ETX 


DC3 


# 


3 


C 


S 


c 


s 


—4 


EOT 


DC4 


$ 


4 


D 


T 


d 


t 


—5 


ENQ 


NAK 


% 


5 


E 


U 


e 


u 


—6 


ACK 


SYN 


& 


6 


F 


V 


f 


V 


—7 


BEL 


ETB 


t 


7 


G 


W 


8 


w 


—8 


BS 


CAN 


( 


8 


H 


X 


h 


X 


—9 


HT 


EM 


) 


9 


I 


Y 


i 


y 


—A 


LF 


SUB 


* 




J 


Z 


j 


z 


— B 


VT 


ESC 


+ 


» 


K 


[ 


k 


{ 


— C 


FF 


FS 




< 


L 


\ 


I 


1 


— D 


CR 


GS 






M 


] 


m 


} 


— E 


SO 


RS 




> 


N 




n 




— F 


SI 


US 


/ 


7 


O 




o 


RUB 
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C94 - Internal Character Representation 





0— 


1— 


2— 


3— 


4— 


5— 


6— 


7— 


— 1 


A 


/ 


Q 


Y 


5 


— + 


e 


i 


—3 


B 


/ 


R 


Z 


6 


P 


/ 


t 


—5 


C 


K 


S 




7 




-f 


? 


—7 


D 


L 


T 





8 




\ 




g 


p 


M 


IT 


1 


o 






+ 


B 


p 




V 

V 


2 


(D 




T 

1 




n 






W 

vr 


■J 


A 


9 


1 


X 


p 


fj 


P 


X 


4 


Y 


d) 


€ 
























fi 

o 


a 


A 


R 




2> 


E 


F— 


— 1 


r 


A 




» 




U 





CRFWD 


—3 


L 


V 






o 


I 




CRDWN 


—5 


* 


A 


( 




□ 


$ 




CRUP 


—7 


» 


< 


) 




□ 


H 




CLEAR 


—9 


1 


< 


• 


U 


C 


1- 




HOME 


—B 


I 






«— 


D 


{ 




CR 


—D 


o 


> 


[ 


a 


n 


} 




EEOL 


—F 


V 


> 


1 


V 


Pi 


A 




CRBCK 



NOTE: 

1 Since only odd-numbered entries have meaning, only those are shown here. 



Commodore Magazine 



This bi-monthly magazine, published by Commodore, provides a vehicle for sharing the 
latest product information on Commodore systems, programming techniques, hardware 
interfacing, and applications for the CBM, PET, SuperPET, and VIC Systems. Each issue 
contains user application features, columns by leading experts, the latest news on user 
clubs, a question/answer hotline column, and reviews of the latest books and software. 

The subscription fee is $15.00 for six issues per year within the U.S. and its possessions, 
and $25.00 for Canada and Mexico. Make checks payable to COMMODORE BUSINESS 
MACHINES, and send to: 

Editor, Commodore Magazine 
Commodore Business Machines, Inc. 
681 Moore Road 
King of Prussia, PA 19406 



The Transactor 

The Transactor, which is a monthly publication of Commodore-Canada, is primarily a 
technical periodical, containing pertinent hardware and software information for the 
CBM, PET, VIC, and SuperPET systems. Each issue features product reviews, hardware 
and software evaluations, and programming tips from the finest technical experts on 
Commodore products. Additionally, The Transactor contains general information such 
as product updates and trade show reports. 

The subscription fee is $10.00 for six issues within Canada and the United States, and 
$13.00 for all foreign countries. Make checks payable to COMMODORE BUSINESS 
MACHINES, INC. and send to: 

Editor, The Transactor 

Commodore Business Machines, Inc. 

3370 Pharmacy Avenue 

Agincourt, Ontario, Canada M1W 2K4 



APL is a powerful and concise programming language which is ideally 
suited for the analysis of financial, statistical and engineering data, 
database applications and data communications. One of its chief 
characteristics is the speed with which computer applications can be 
developed, and the ease with which existing programs may be 
modified. The language enjoys a high degree of standardization. 

Waterloo microAPL follows closely IBM's internal standard of APL. 
All the standard language features consistent with a single-user 
environment are included. 

Features and Extensions 

■ All the standard primitive functions and operators 

■ No limitations (other than workspace size) on array ranks 
or shapes 

■ Up to 80-character names 

■ Direct, fast screen access and cursor control 

■ Full-screen editing 

■ Blanks retained in defined functions for readability 

■ Ability to read and modify memory 

■ Ability to execute machine language functions 

■ Sequential files of APL arrays 

■ Arbitrary sequential files 

■ All system functions for function establishment, canonical 
representation, latent expression, etc. 

This manual is presented in two parts: a tutorial introduction to 
microAPL and a comprehensive reference manual. Appendices are 
included which contain summaries of the language primitives and 
system features. 



DISTRIBUTED BY 

HoujQrd UU. Sams & Co.. Inc. 

4300 WEST 62ND ST. INDIANAPOLIS, INDIANA 46268 USA 
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